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IV. MEMORANDUM MACROS 
1. Introduction 
1.1 Purpose 


This section is a guide and reference manual for users of Memorandum Macros (MM). These macros provide 
a general purpose package of text formatting macros for use with the UNIX operating system text formatters 


nroff and troff (refer to troff(1) in the User’s Manual—UNIX Operating System for more details). A reference 
of the form name(N) points to page name in section Nof the User's Manual. 


1.2 Conventions 


Each part of this section explains a single facility of MM. In general, the earlier a part occurs, the more 
necessary the information is for most users. Some of the later parts can be completely ignored if MM defaults 
are acceptable. Likewise, each part progresses from general case to special-case facilities. It is recommended 
that a user read a part in detail only to the point where there is enough information to obtain the desired format, 
then skim the rest of the part because some details may be of use to only a few, 


Numbers enclosed in curly brackets ({}) refer to paragraph numbers within this section. For example, this 
is paragraph {1.2}. 


In the synopses of macro calls, square brackets ([ ]) surrounding an argument indicate that it is optional. 
Ellipses (...) show that the preceding argument may appear more than once. 


Figure 4.1 shows both nroff and troff formatter outputs (of files using MM macros) for a simple letter. 
In those cases in which the behavior of the two formatters is obviously different, the nroff formatter output 
is described first with the troff formatter output following in parentheses. For example: 


The title is underlined (italic). 
means that the title is underlined by the nroff formatter and italicized by the troff formatter. 


1.3 Document Structure 


Input for a document to be formatted with the MM text formatting macro package has four major segments, 
any of which may be omitted; if present, the segments must occur in the following order: 


e Parameter setting segment sets the general style and appearance of a document. The user can control 
page width, margin justification, numbering styles for heading and lists, page headers and footers {9}, 
and many other properties of the document. Also, the user can add macros or redefine existing ones. 
This segment can be omitted entirely if the user is satisfied with default values; it produces no actual 
output, but performs only the formatter setup for the rest of the document. 


e Beginning segment includes those items that occur only once, at the beginning of a document, e.g., title, 
author’s name, date. 


e Body segment is the actual text of the document. It may be as small as a single paragraph or as large 
as hundreds of pages. It may have a hierarchy of headings up to seven levels deep {4}, Headings are auto- 
matically numbered (if desired) and can be saved to generate the table of contents. Five additional levels 
of subordination are provided by a set of list macros for automatic num bering, alphabetic sequencing, 
and “marking” of list items {5}. The body may also contain various types of displays, tables, figures, ref- 
erences, and footnotes {7, 8, 11}. 


e Ending segment contains those items that occur only once at the end of a document, Included are signa- 
ture(s) and lists of notations (e.g., “Copy to” lists) {6.11}. Certain macros may be invoked here to print 
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information that is wholly or partially derived from the rest of the document, such as the table of con- 
tents or the cover sheet for a document {10}. 

Existence and size of these four segments varies widely among different document types. Although a spe- 
cific item (such as date, title, author names, etc.) may differ depending on the document, there is a uniform way 
of typing it into an input text file. 

1.4 Input Text Structure 
In order to make it easy to edit or revise input file text at a later time. 
e Input lines should be kept short 
e Lines should be broken at the end of clauses 
e Each new sentence should begin on a new line. 
1.5 Definitions 


Formatter refers to either the nroff or troff text-formatting program. 


Requests are built-in commands recognized by the formatters. Although a user seldom needs to use these 
requests directly {3.10}, this section contains references to some of the requests. For example, the request 


Sp 
inserts a blank line in the output at the place the request occurs in the input text file. 


Macros are named collections of requests. Each macro is an abbreviation for a collection of requests that 
would otherwise require repetition. The MM package supplies many macros, and the user can define additional 
ones. Macros and requests share the same set of names and are used in the same way. 


Table 4.A is an alphabetical list of macro names used by MM. The first line of each item lists the name of 
the macro, a brief description, and a reference to the paragraph in which the macro is described. The second 
line illustrates a typical call of the macro. 


Strings provide character variables, each of which names a string of characters. Strings are often used 
in page headers, page footers, and lists. These registers share the pool of names used by requests and macros. 
A string can be given a value via the .ds (define string) request; and its value can be obtained by referencing 
its name, preceded by “\*” (for 1-character names) or “\*(” (for 2-character names). For instance, the string 
DT in MM normally contains the current date, thus the input line 

Today is \*(DT. 
may result in the following output: 
Today is December 16,1981. 
The current date can be replaced, e.g.: 


.ds DT 01/01/79 


by invoking a macro designed for that purpose {6.8}. Table 4.B is an alphabetical list of string names used by 
MM. A brief description, paragraph reference, and initial (default) value(s) are given for each. 
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Number registers fill the role of integer variables. These registers are used for flags and for arithmetic 
and automatic numbering. A register can be given a value using a .nr request and be referenced by preceding 
its name by \n (for 1-character names) or \n( (for 2-character names). For example, the following sets the value 
of the register d to one more than that of the register dd: 


cnr d 1+\n(dd 


Table 4.C is an alphabetical list of number register names giving for each a brief description, paragraph refer- 
ence, initial (default) value, and legal range of values (where [m:n] means values from m to n, inclusive. 


Paragraph 14.1 contains naming conventions for requests, macros, strings, and number registers. Table 4.A, 
4.B, and 4.C list all macros, strings, and number registers defined in MM. 


2. Usage 


This part describes how to access MM, illustrates UNIX operating system command lines appropriate for 
various output devices, and describes command line flags for the MM text formatting macro package. 


2.1 The mm Command 


The mm(1) command can be used to prepare documents using the nroff formatter and MM; this command 
invokes nroff with the —cm flag {2.2}. The mm command has options to specify preprocessing by tbl and/or 
by neqn and for postprocessing by various output filters. Any arguments or flags that are not recognized by 
the mm command, e.g., —rC3, are passed to the nroff formatter or to MM, as appropriate. Options, which can 
occur in any order but must appear before the file names, are: 


OPTION MEANING 

—e The negn is to be invoked; also causes neqn to read /usr/pub/eqnchar [see eqnehar(7)]. 

—t The tbl(1)is to be invoked. 

-¢ The col(1)is to be invoked. 

—E The —e option of the nroff formatter is to be invoked. 

=y. The —mm (uncompacted macros) is to be used instead of —em. 

mall? The 12-pitch mode is to be used. The pitch switch on the terminal should be set to 12 if nec- 
essary. 

—T450 Output is toa DASI 450. This is the default terminal type [unless $TERM is set; see sh(1)]. 
It is also equivalent to —-T1620. 

_~T450—-12 Output is to a DASI 450 in 12-pitch mode. 

—T300 Output is to a DASI 300 terminal. 

—T300-—12 Output is to a DASI 300 in 12-pitch mode. 

—T300s Output is to a DASI 3008. 

—T300s—12 Output is to a DASI 3008 in 12-pitch mode. 

—T4014 Output is to a Tektronix 4014, 
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OPTION MEANING 

= PST Output is to a TELETYPE® Model 37. 

—T382 Output is to a DTC-382. 

—T4000a Output is to a Trendata 4000A. 

= Output is prepared for an EBCDIC line printer. 

—Thp Output is to an HP264x (implies —c). 

—T43 Output is to a TELETYPE® Model 43 (implies —c). 

—T40/4 Output is to a TELETYPE® Model 40/4 (implies —c). 

=—i4o Output is to a Texas Instrument 700 series terminal (implies —c). 

—T2631 Output is prepared for an HP2631 printer where -T2631—e and —T2631—c may be used for 
expanded and compressed modes, respectively (implies —c). 

—Tlp gi : to a device with no reverse or partial line motions or other special features (im- 
plies —c). 


Any other —T option given does not produce an error; it is equivalent to —Tlp. 
A similar command is available for use with the troff formatter | mmt(1)]. 


2.2 The —cm or —mm Flag 


The MM package can also be invoked by including the —cm or —mm flag as an argument to the formatter. 
The —cm flag causes the precompacted version of the macros to be loaded. The —mm flag causes the file 
/usr/lib/tmac/tmac.m to be read and processed before any other files, This action defines the MM macros, sets 
default values for various parameters, and initializes the formatter to be ready to process the input text files. 


2.3 Typical Command Lines 
The prototype command lines are as follows (with the various options explained in {2.4}): 
e Text without tables or equations: 
mm [options] file ... 


or 
nroff [options] —cm file ... 


mmt [options] file ... 
or 
troff [options] —cm file ... 


e Text with tables: 


mm —t [options] file ... 


or 
tbl file ... i nroff [options] —cm 
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mmt —t [options] file ... 
or 
tbl file ... i troff [options] —em 


e Text with equations: 


mm —e [options] file ... 
or 
neqn /usr/pub/eqnchar file ... | nroff [options] —em 


mmt ~—e [options] file ... 

or 

eqn /usr/pub/eqnchar file ... | troff [options] —cm 
e Text with both tables and equations: 


mm —t —e [options] file ... 
or 
tbl file ... i neqn /usr/pub/eqnchar — | nroff [options] —em 


mmt —t —e [options] file ... 
or 
tbl file ... i eqn /usr/pub/eqnchar — | troff \ [options] —em 


When formatting a document with the nroff processor, the output should normally be processed for a spe- 
cific type of terminal because the output may require some features that are specific to a given terminal, e.g., 
reverse paper motion or half-line paper motion in both directions. Some commonly used terminal types and the 
command lines appropriate for them are given below. More information is found in paragraph {2.4} of this part, 
and 300(1), 450(1), 4014(1), hp(1), col(1), termio(4), and term(5) of the User’s Manual — UNIX Operating 
System. 


e DASI 450 in 10-pitch, 6 lines/inch mode, with 0.75 inch offset, and a line length of 6 inches (60 charac- 
ters) where this is the default terminal type so no —T option is needed (unless $TERM is set to another 
value): 


mm file ... 
or 
nroff —T450 —h —cm file ... 


e DASI 450 in 12-pitch, 6 lines/inch mode, with 0.75 inch offset, and a line length of 6 inches (72 charac- 
ters): 


mm ~—12 file ... 

or 

nroff —T450—12 —h —ecm file ... 

or to increase the line length to 80 characters and decrease the offset to 3 characters: 


mm —12 —rW80 —rO3 file ... 

or 

nroff —T450—12 —rW80 —r03 —h —em file ... 
e Hewlett-Packard HP264x CRT family: 


mm —Thp file ... 
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or 
nroff —em file ...t col | hp 


e Any terminal incapable of reverse paper motion and also lacking hardware tab stops (Texas Instru- 
ments 700 series, etc.): 


mm —T745 file ... 
or 
nroff —em file ... | col —x 


The thl(1) and eqn(1)/neqn formatters, if needed, must be invoked as shown in the command lines illus- 
trated earlier. 


If 2-column processing {12.4} is used with the nroff formatter, either the —c option must be specified to 
mm(1) [mm(1) uses col(1) automatically for many terminal types {2.1}] or the nroff formatter output must 
be postprocessed by col(1). In the latter case, the —T37 terminal type must be specified to the nroff formatter, 
the —h option must not be specified, and the output of col(1) must be processed by the appropriate terminal 
filter [e.g., 450(1)]; mm(1) with the —c option handles all this automatically. 


2.4 Parameters Set From Command Line 


Number registers are commonly used within MM to hold parameter values that control various aspects of 
output style. Many of these values can be changed within the text files with nr requests. In addition, some of 
these registers can be set from the command line. This is a useful feature for those parameters that should not 
be permanently embedded within the input text. If used, the number registers (with the possible exception of 
the register P below) must be set on the command line (or before the MM macro definitions are processed). The 
number register meanings are: 


REGISTER MEANING 


—rAn n=1 has effect of invoking the .AF macro without an argument {6.9} . 
n= 2 permits use of Bell System logo, if available, on a printing device (currently available 
for Xerox 9700 only). 


—rCn — sets type of copy (e.g., DRAFT) to be printed at bottom of each page {9.2.4}. 
n= 1 for OFFICIAL FILE COPY. 
n= 2 for DATE FILE COPY. 
n = 3 for DRAFT with single spacing and default paragraph style. 
n = 4 for DRAFT with double spacing and 10-space paragraph indent. 


—rD1 sets debug mode. 
This flag requests formatter to continue processing even if MM detects errors that would 
otherwise cause termination. It also includes some debugging information in the default 
page header {9.2.1, 12.3}. 
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MEANING 


controls font of Subject/Date/From fields. 
n = (0), fields are bold (default for the troff formatter). 
n= 1, fields are Roman font (regular text-default for the nroff formatter). 


sets length of physical page to k lines. 

For the nroff formatter, k is an unscaled number representing lines. 

For the troff formatter, k must be scaled. 

Default value is 66 lines per page. 

This flag is used, for example, when directing output to a Versatec* printer. 


specifies page numbering style. 

n= 0 (default), all pages get the prevailing header {9.2.1} . 

n = 1, page header replaces footer on page 1 only. 

n= 2, page header is omitted from page 1. 

n = 3, “section-page” numbering {4.5} occurs (FD {8.3} and .RP {11.4} defines 
footnote and reference numbering in sections). 

n= 4, default page header is suppressed; however, a user-specified header is not affected. 
n= 5, “section-page” and “section-figure” numbering occurs. 


header header 
header replaces footer header 


no header header 

“section-page” as footer same as page 1 

no header no header unless .PH defined 
“section-page” as footer and “section-figure” same as page 1 


rok 


— that 


=fSi 


Contents of the prevailing header and footer do not depend on number register Nvalue; N 
controls only whether the header (N=3) or the footer (N=5) is printed, as well as the page 
numbering style. If header and footer are null {9.2.1, 9.2.4}, the value of Nis irrelevant. 
offsets output A spaces to the right. 

For the nroff formatter, kis an unscaled number representing lines or character positions. 
For the troff formatter, k must be scaled. 

This flag is helpful for adjusting output positioning on some terminals. The default offset, 
if this regular is not set on the command line, is 0.75 inches. 


Note: Register name is the capital letter “O”. 


specifies that pages of the document are to be numbered starting with nm. 
This register may also be set via a .nr request in the input text. 


sets point size and vertical spacing for the document. The default mis 10, i-e., 10-point type 
on 12-point vertical spacing, giving six lines per inch {12.9} . This flag applies to the troff 
formatter only. 


* Registered Trademark of Versatec, Inc. 
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REGISTER 


=n 


=FUl 


—rWk 


MEANING 


provides register settings for certain devices. 

If mis 1, line length and page offset are set to 80 and 3, respectively. 

Setting nto 2 changes the page length to 84 lines per page and inhibits underlining; it is 
meant for output sent to the Versatec printer. 

The default value for n is 0. 

This flag applies to the nroff formatter only. 


controls underlining of section headings. 

This flag causes only letters and digits to be underlined. Otherwise, all characters (includ- 
ing spaces) are underlined {4.2.2.4.2}. 

This flag applies to the nroff formatter only. 


sets page width (line length and title length) to k. 

For the nroff formatter, k is an unscaled number representing character positions. 

For the troff formatter, k must be scaled. 

This flag can be used to change page width from the default value of 6 inches (60 charac- 
ters in 10 pitch or 72 characters in 12 pitch). 


2.5 Omission of —cm or —mm Flag 


If a large number of arguments is required on the command line, it may be convenient to set up the first 
(or only) input file of a document as follows: 


zero or more initializations of registers listed in {2.4} 
so /usr/lib/tmac/tmac.m 
remainder of text 


In this case, the user must not use the —em or —mm flag [nor the mm(1) or mmt(1) command]; the .so 
request has the equivalent effect, but registers in {2.4} must be initialized before the .so request because their 
values are meaningful only if set before macro definitions are processed. When using this method, it is best to 
lock into the input file only those parameters that are seldom changed. For example: 


.or W 80 

-nr O 10 

or N3 

so /usr/lib/tmac/tmac.m 
-H 1" INTRODUCTION" 


specifies, for the nroff formatter, a line length (W) of 80, a page offset (O) of 10, and “section-page” (N) number- 


ing. 


3. Formatting Concepts 


3.1 Basic Terms 


Normal action of the formatters is to fill output lines from one or more input lines. Output lines may be 
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justified so that both the left and right margins are aligned. As lines are being filled, words may also be hyphen- 
ated {3.4} as necessary. It is possible to turn any of these modes on and off (.SA {12.2}, Hy {3.4}, and the .nf and 
.fi formatter requests). Turning off fill mode also turns off justification and hyphenation. 


Certain formatting commands (requests and macros) cause filling of the current output line to cease, the 
line (of whatever length) to be printed, and subsequent text to begin a new output line. This printing of a par- 
tially filled output line is known as a break. A few formatter requests and most of the MM macros cause a break. 


Formatter requests {8.10} can be used with MM; however, there are consequences and side effects that each 
such request might have. A good rule is to use formatter requests only when absolutely necessary. The MM 
macros described herein should be used in most cases because: 


e It is much easier to control (and change at any later point in time) overall style of the document. 
e Complicated features (such as footnotes or tables of contents) can be obtained with ease. 
e User is insulated from peculiarities of the formatter language. 

3.2 Arguments and Double Quotes 


For any macro call, a null argument is an argument whose width is zero. Such an argument often has a spe- 
cial meaning; the preferred form for a null argument is"". Omitting an argument is not the same as supplying 
a null argument (e.g., the .MT macro in {6.7}). Omitted arguments can occur only at the end of an argument 
list; null arguments can occur anywhere in the list. 


Any macro argument containing ordinary (paddable) spaces must be enclosed in double quotes. A double 
quote ("') is a single character that must not be confused with two apostrophes or acute accents (’) or with two 
grave accents ("'). Otherwise, it will be treated as several separate arguments. 


Double quotes are not permitted as part of the value of a macro argument or of a string that is to be used 
as a macro argument. If it is necessary to have a macro argument value, two grave accents (\‘) and/or two acute 
accents (””) may be used instead. This restriction is necessary because many macro arguments are processed (in- 
terpreted) a variable number of times. For example, headings are first printed in the text and may be reprinted 
in the table of contents. 


3.3 Unpaddable Spaces 


When output lines are justified to give an even right margin, existing spaces in a line may have additional 
spaces appended to them. This may distort the desired alignment of text. To avoid this distortion, it is necessary 
to specify a space that cannot be expanded during justification, i.e., an unpaddable space. There are several ways 
to accomplish this: 


e The user may type a backslash followed by a space (\_). This pair of characters directly generates an 
unpaddable space. 


e The user may sacrifice some seldom-used character to be translated into a space upon output. 
Because this translation occurs after justification, the chosen character may be used anywhere an unpaddable 
space is desired. The tilde (~) is often used with the translation macro for this purpose. To use the tilde in this 
way, the following is inserted at the beginning of the document: 

ec 8 ae 


If a tilde must actually appear in the output, it can be temporarily “recovered” by inserting 


ae 
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before the place where needed. Its previous usage is restored by repeating the .tr ~ after a break or after the 
line containing the tilde has been forced out. 


Note: Use of the tilde in this fashion is not recommended for documents in which the tilde is used within 
equations. 


3.4 Hyphenation 


Formatters do not perform hyphenation unless requested. Hyphenation can be turned on in the body of the 
text by specifying 


nr Hy 1 


once at the beginning of the document input file. Paragraph 8.3 describes hyphenation within footnotes and 
across pages, 


If hyphenation is requested, formatters will automatically hyphenate words if need be. However, the user 
may specify hyphenation points for a specific occurrence of any word with a special character known as a hy- 
phenation indicator or may specify hyphenation points for a small list of words (about 128 characters). 


If the hyphenation indicator (initially, the 2-character sequence “\'%”’) appears at the beginning of a word, 
the word is not hyphenated. Alternatively, it can be used to indicate legal hyphenation points inside a word. 
All occurrences of the hyphenation indicator disappear on output. 


The user may specify a different hyphenation indicator. 
-HC [hyphenation-indicator] 


The circumflex (* ) is often used for this purpose by inserting the following at the beginning of a document 
input text file: 


-HC * 


Note: Any word containing hyphens or dashes (also known as em dashes) will be hyphenated immedi- 
ately after a hyphen or dash if it is necessary to hyphenate the word, even if the formatter hyphenation 
function is turned off. 


The user may supply, via the exception word .hw request, a small list of words with the proper hyphenation 
points indicated. For example, to indicate the proper hyphenation of the word “printout”, the user may specify 


-hw print-out 
3.5 Tabs 


Macros .MT {6.7}, .TC {10.1}, and .CS {10.2} use the formatter tabs .ta request to set tab stops and then re- 
store the default values of tab settings (every eight characters in the nroff formatter; every 2 inch in the troff 
formatter). Setting tabs to other than the default values is the user’s responsibility. 


Default tab setting values are 9, 17, 25, ..., 161 for a total of 20 tab stops. Values may be separated by commas, 
spaces, or any other non-numeric character. A user may set tab stops at any value desired. For example: 


a 917 25 33 41 49 57 ... 161 


A tab character is interpreted with respect to its position on the input line rather than its position on the 
output line. In general, tab characters should appear only on lines processed in no-fill (nf) mode {3.1}. 
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The tbl(1) program {7.3} changes tab stops but does not restore default tab settings. 


3.6 BEL Character 


The nonprinting character BEL is used as a delimiter in many macros to compute the width of an argument 
or to delimit arbitrary text, e.g., in page headers and footers {9}, headings {4}, and lists {5}. Users who include 
BEL characters in their input text file (especially in arguments to macros) will receive mangled output. 


3.7 Bullets 


A bullet (e) is often obtained on a typewriter terminal by using an “o” overstruck by a “+”, For compatibil 
ity with the troff formatter, a bullet string is provided by MM with the following sequence: 


\*(BU 
The bullet list (BL) macro {5.1.1.2} uses this string to generate automatically the bullets for bullet-listed items. 
3.8 Dashes, Minus Signs, and Hyphens 


The troff formatter has distinct graphics for a dash, a minus sign, and a hyphen; the nroff formatter does 
not. 


e Users who intend to use the nroff formatter only may use the minus sign (--) for the minus, hyphen, 
and dash. 


e Users who plan to use the troff formatter primarily should follow troff escape conventions. 

e Users who plan to use both formatters must take care during input text file preparation. Unfortunately, 
these graphic characters cannot be represented in a way that is both compatible and convenient for both 
formatters. 

The following approach is suggested: 

SYMBOL ACTION 
Dash Type \*(EM for each text dash for both nroff and troff formatters. This string generates 
an em dash in the troff formatter and two dashes (——) in the nroff formatter. Dash list 


(.DL) macros {5.2.1.3} automatically generate the em dash for each list item. 


Hyphen Type - and use as is for both formatters. The nroff formatter will print it as is, and the 
troff formatter will print - (a true hyphen). 


Minus Type \— for a true minus sign regardless of formatter. The nroff formatter will effectively 


ignore the “\”; the troff formatter will print a true minus sign. 


3.9 Trademark String 


A trademark string \*(Tm is available with MM. This places the letters “TM” one-half line above the text 
that it follows. For example: 


The 

A 

User’s Manual—UNIX 
.R 
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\h’-1’\*(Tm 
I 


Operating System 
.R 
is available from the library. 


yields: 


The User’s Manual—UNIX™ Operating System is available from the library. 
3.10 Use of Formatter Requests 


Most formatter requests should not be used with MM because MM provides the corresponding formatting 
functions in a much more user-oriented and surprise-free fashion than do the basic formatter requests. Howev- 
er, some formatter requests are useful with MM, namely the following: 


val Assign format 

-br Break 

ce Center 

.de Define macro 

.ds Define string 

fi Fill output lines 

-hw Exception word 

ls Line spacing 

nf No filling of output lines 

nr Define and set number register 
nx Go to next file (does not return) 
rm Remove macro 

be Remove register 

Is Restore spacing 

.80 Switch to source file and return 
Sp Space 

.ta Tab stop settings 

ti Temporary indent 

tl Title 

Bis Translate 

J Escape 


The .fp, .lg, and .ss requests are also sometimes useful for the troff formatter. Use of other requests with- 
out fully understanding their implications very often leads to disaster. 


4. Paragraphs and Headings 


4.1 Paragraphs 


-P [type] 
one or more lines of text. 


The .P macro is used to control paragraph style. 


4.1.1 Paragraph Indention 


An indented or a nonindented paragraph is defined with the type argument. 
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type Result 


0 left justified 
1 indent 


In a left-justified paragraph, the first line begins at the left margin. In an indented paragraph, the para- 
graph is indented the amount specified in the Piregister (default value is 5). For example, to indent paragraphs 
by ten spaces, the following is entered at the beginning of the document input file: 


nr Pi 10 
A document input file possesses a default paragraph type obtained by specifying “.P” before each paragraph 
that does not follow a heading {4.2}. Default paragraph type is controlled by the Pt number register. The initial 
value of Ptis 0, which provides left-justified paragraphs. 


All paragraphs can be forced to be indented by inserting the following at the beginning of the document 
input file: 


nr Pt 1 


All paragraphs can be indented except after headings, lists, and displays by entering the following at the 
beginning of the document input file: 


nF Pt 2 
Both the Piand Pt register values must be greater than zero for any paragraphs to be indented. 
Note: Values that specify indentation must be unscaled and are treated as character positions, i.e., as 
a number of ens. In the nroff formatter, an en is equal to the width of a character. In the troff formatter, 
an en is the number of points (1 point = 1/72 of an inch) equal to half the current point size. 
Regardless of the value of Pt, an individual paragraph can be forced to be left-justified or indented. The 
“P 0” macro request forces left justification; “.P 1” causes indentation by the amount specified by the register 
PE 
If .P occurs inside a list, the indent (if any) of the paragraph is added to the current list indent {5}. 


4.1.2 Numbered Paragraphs 


Numbered paragraphs may be produced by setting the Npregister to 1. This produces paragraphs numbered 
within first level headings, e.g., 1.01, 1.02, 1.03, 2.01, ete. 


A different style of numbered paragraphs is obtained by using the .nP macro rather than the .P macro for 
paragraphs. This produces paragraphs that are numbered within second level headings. 


-H1 "FIRST HEADING " 
.H 2 "Second Heading " 
nP 

one or more lines of text 


The paragraphs contain a “double-line indent” in which the text of the second line is indented to be aligned with 
the text of the first line so that the number stands out. 


4.1.3 Spacing Between Paragraphs 


The Ps number register controls the amount of spacing between paragraphs. By default, Psis set to 1, yield- 
ing one blank space (one-half a vertical space). 
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4.2 Numbered Headings 


H level [heading-text] [heading-suffix] 
zero or more lines of text 


The .H macro provides seven levels of numbered headings. Level 1 is the highest; level 7 the lowest. 


The heading-suffix argument is appended to the heading-text argument and may be used for footnote marks 
which should not appear with heading text in the table of contents. 


Note: There is no need for a .P macro immediately after a .H or .HU {4.3} because the .H macro also 
performs the function of the .P macro. Any immediately following .P macro is ignored. It is, however, good 
practice to start every paragraph with a .P macro, thereby ensuring that all paragraphs uniformly begin 
with a .P throughout an entire document. 


4.2.1 Normal Appearance 


The effect of the .H macro varies according to argument level. First-level headings are preceded by two 
blank lines (one vertical space); all others are preceded by one blank line (one-half a vertical space). The follow- 
ing table describes the default effect of the level argument. 


H 1 heading-text Produces a bold font heading followed by a single blank line (one- 
half a vertical space). The following text begins on a new line and is 
indented according to the current paragraph type. Full capital let- 
ters should normally be used to make the heading stand out. 


-H 2 heading-text Produces a bold font heading followed by a single blank line (one- 
half a vertical space). The following text begins on a new line and is 
indented according to the current paragraph type. Normally, initial 
capitals are used. 


-H n heading-text Produces an underlined (italicized) heading followed by two spaces 
(3 <n < 7). The following text begins on the same line, i.e., these are 
run-in headings. 


Appropriate numbering and spacing (horizontal and vertical) occur even if the heading-text argument is 
omitted from a .H macro call. 


The following listing gives the first few .H calls used for this part. 


_ -H1 " paragraphs and headings " 
-H 2 " Paragraphs" 
.H 8 " Paragraph Indention " 
.H 3 "Numbered Paragraphs" 
.H3 "Spacing Between Paragraphs " 
.H 2 "Numbered Headings " 
13 "Normal Appearance" 
-H 3 " Altering Appearance " 
.H4 "Prespacing and Page Ejection " 
.H4 "Spacing After Headings " 
H4 "Centered Headings" 
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.H 4 " Bold, Italic, and Underlined Headings " 
.H 5 “Control by Level” 


Note: Users satisfied with the default appearance of headings may skip to the paragraph entitled “Un- 
numbered Headings” {4.3}. 


4.2.2 Altering Appearance 


The user can modify the appearance of headings quite easily by setting certain registers and strings at the 
beginning of the document input text file. This permits quick alteration of a document’s style because this style- 
control information is concentrated in a few lines rather than being distributed throughout the document. 


4.2.2.1 Prespacing and Page Ejection 


A first-level heading (.H 1) normally has two blank lines (one vertical space) preceding it, and all other head- 
ings are preceded by one blank line (one-half a vertical space). If a multiline heading were to be split across 
pages, it is automatically moved to the top of the next page. Every first-level heading may be forced to the top 
of a new page by inserting 


nr Kj 1 


at the beginning of the document input text file. Long documents may be made more manageable if each section 
starts on a new page. Setting the Ej register to a higher value causes the same effect for headings up to that 
level, i.e., a page eject occurs if the heading level is less than or equal to the Fj value. 


4.2.2.2 Spacing After Headings 


Three registers control the appearance of text immediately following a .H call. The registers are Hb (head- 
ing break level), Hs (heading space level), and Hi (post-heading indent). 


If the heading level is less than or equal to Hb, a break {3.1} occurs after the heading. If the heading level 
is less than or equal to Hs, a blank line (one-half a vertical space) is inserted after the heading. The default 
value for Hb and Hs is 2. If a heading level is greater than Hb and also greater than Hs, then the heading (if 
any) is run into the following text. These registers permit headings to be separated from the text in a consistent 
way throughout a document while allowing easy alteration of white space and heading emphasis. 


For any stand-alone heading, i.e., a heading not run into the following text, alignment of the next line of 
output is controlled by the Hi register. 


e If Hiis 0, text is left-justified. 


e If Hiis 1 (the default value), text is indented according to the paragraph type as specified by the Pt reg- 
ister {4.1}. 


e If Hiis 2, text is indented to line up with the first word of the heading itself so that the heading number 
stands out more clearly. 


To cause a blank line (one-half a vertical space) to appear after the first three heading levels, to have no 
run-in headings, and to force the text following all headings to be left-justified (regardless of the value of Pt), 
the following should appear at the beginning of the document input text file: 


.or Hs 3 
or Hb 7 
cnr Hi 0 
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4.2.2.3 Centered Headings 


The He register can be used to obtain centered headings. A heading is centered if its level argument is less 
than or equal to He and if it is also a stand-alone heading {4.2.2.2}. The He register is 0 initially (no centered 
headings). 


4.2.2.4 Bold, Italic, and Underlined Headings 
4.2.2.4.1 Control by Level: Any heading that is underlined by the nroff formatter is italicized by the troff 


formatter. The string HF (heading font) contains seven codes that specify fonts for heading levels 1 through 
7. Legal codes, code interpretations, and defaults for HF codes are: 


no underline underline bold 
Roman italic bold 


DEFAULT 


Thus, levels 1 and 2 are bold; levels 3 through 7 are underlined by the nroff formatter and italicized by the 
troff formatter. The user may reset HF as desired. Any value omitted from the right end of the list is assumed 
to be a 1. The following request would result in five bold levels and two Roman font levels: 

ds HF 33333 
4.2.2.4.2 NROFF Underlining Style: The nroff formatter underlines in either of two styles: 
e The normal style (.ul request) is to underline only letters and digits. 
e The continuous style (.cu request) underlines all characters including spaces. 
By default, MM attempts to use the continuous style on any heading that is to be underlined and is short enough 
to fit on a single line. If a heading is to be underlined but is longer than a single line, the heading is underlined 


in the normal style. 


All underlining of headings can be forced to the normal style by using the —rU1 flag when invoking the 
nroff formatter {2.4}. 


4.2.2.4.3 Heading Point Sizes: The user may specify the desired point size for each heading level with the HP 
string (for use with the troff formatter only). 


.ds HP [ps1] [ps2] [ps3] [ps4] [ps5] [ps6] [ps7] 


By default, the text of headings (.H and .HU) is printed in the same point size as the body except that bold 
stand-alone headings are printed in a size one point smaller than the body. The string HP, similar to the string 


HF, can be specified to contain up to seven values, corresponding to the seven levels of headings. For example: 


.ds HP 12 12 10 10 10 10 10 


specifies that the first and second level headings are to be printed in 12-point type with the remainder printed 
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in 10-point. Specified values may also be relative point-size changes, for example: 
ds HP +2 +2 -1 -1 
If absolute point sizes are specified, then absolute sizes will be used regardless of the point size of the body of 


the document. If relative point sizes are specified, then point sizes for headings will be relative to the point size 
of the body even if the latter is changed. 


Null or zero values imply that default size will be used for the corresponding heading level. 


Note: Only the point size of the headings is affected. Specifying a large point size without providing in- 
creased vertical spacing (via .HX and/or .HZ) may cause overprinting. 


4.2.2.5 Marking Styles-Numerals and Concatenation 
-HM [arg1] ... [arg7] 


The registers named H1 through H7are used as counters for the seven levels of headings. Register values 
are normally printed using Arabic numerals. The .HM macro (heading mark style) allows this choice to be 
overridden thus providing “outline” and other document styles. This macro can have up to seven arguments; 
each argument is a string indicating the type of marking to be used. Legal arguments and their meanings are: 


ARGUMENT MEANING 
1 Arabic (default for all levels) 
0001 Arabic with enough leading zeroes to get the specified number of digits 
A Uppercase alphabetic 
a Lowercase alphabetic 
I Uppercase Roman 
i Lowercase Roman 


Omitted arguments are interpreted as 1; illegal arguments have no effect. 


By default, the complete heading mark for a given level is built by concatenating the mark for that level 
to the right of all marks for all levels of higher value. To inhibit the concatenation of heading level marks, i.e., 
to obtain just the current level mark followed by a period, the heading mark type register (Ht) is set to 1. For 
example, a commonly used “outline” style is obtained by: 


HMI Alai 
-or Ht 1 


4.3 Unnumbered Headings 


-HU heading-text 


The .HU macro is a special case of .H; it is handled in the same way as .II except that no heading mark 
is printed. In order to preserve the hierarchical structure of headings when .H and .HU ealls are intermixed, 
each .HU heading is considered to exist at the level given by register Hu, whose initial value is 2. Thus, in the 
normal case, the only difference between 


-HU heading-text 


Page 173 


DOCUMENT PROCESSING GUIDE ISSUE 1 6/82 


and 
.H 2 heading-text 


is the printing of the heading mark for the latter. Both macros have the effect of incrementing the numbering 
counter for level 2 and resetting to zero the counters for levels 3 through 7. Typically, the value of Hu should 
be set to make unnumbered headings (if any) be the lowest-level headings in a document. 


The .HU macro can be especially helpful in setting up appendices and other sections that may not fit well 
into the numbering scheme of the main body of a document {14.2.1}. 


4.4 Headings and Table of Contents 


The text of headings and their corresponding page numbers can be automatically collected for a table of 
contents. This is accomplished by doing the following: 


e specifying in the contents level register, Cl, what level headings are to be saved 
e invoking the .TC macro {10.1} at the end of the document. 


Any heading whose level is less than or equal to the value of the Cl register is saved and later displayed 
in the table of contents. The default value for the C] register is 2, i.e., the first two levels of headings are saved. 


Due to the way headings are saved, it is possible to exceed the formatter’s storage capacity, particularly 
when saving many levels of many headings, while also processing displays {7} and footnotes {8}. If this happens, 
the “Out of temp file space” formatter error message (Table 4.D) will be issued; the only remedy is to save fewer 
levels and/or to have fewer words in the heading text. 


4.5 First-Level Headings and Page Numbering Style 


By default, pages are numbered sequentially at the top of the page. For large documents, it may be desirable 
to use page numbering of the “section-page” form where “section” is the number of the current first-level head- 
ing. This page numbering style can be achieved by specifying the —rN3 or —rN5 flag on the command line {9.3}. 
As a side effect, this also has the effect of setting Kj to 1, i.e., each first level section begins on a new page. In 
this style, the page number is printed at the bottom of the page so that the correct section number is printed. 


4.6 User Exit Macros 
Note: This paragraph is intended primarily for users who are accustomed to writing formatter macros. 


-HX dlevel rlevel heading-text 
-HY dlevel rlevel heading-text 
.HZ dlevel rlevel heading-text 


The .HX, .HY, and .HZ macros are the means by which the user obtains a final level of control over the 
previously described heading mechanism. These macros are not defined by MM. These macros are intended to 
be defined by the user. The .H macro invokes .H1X shortly before the actual heading text is printed; it calls HZ 
as its last action. After .HX is invoked, the size of the heading is calculated. This processing causes certain fea- 
tures that may have been included in .HX, such as .ti for temporary indent, to be lost. After the size calculation, 
HY is invoked so that the user may respecify these features. All default actions occur if these macros are not 
defined. If .HX, HY, or .HZ are defined by the user, user-supplied definition is interpreted at the appropriate 
point. These macros can therefore influence handling of all headings because the HU macro is actually a special 
case of the .H macro. 


If the user originally invoked the .H macro, then the derived level (devel) and the real level (rlevel) are both 
equal to the level given in the .H invocation. If the user originally invoked the .HU macro {4.3}, dlevel is equal 
to the contents of register Hu, and rlevel is 0. In both cases, heading-text is the text of the original invocation. 
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By the time .H calls .HX, it has already incremented the heading counter of the specified level {4.2.2.5}, pro- 
duced blank lines (vertical spaces) to precede the heading {4.2.2.1}, and accumulated the “heading mark”, i.e., 
the string of digits, letters, and periods needed for a numbered heading. When .HX is called, all user-accessible 
registers and strings can be referenced, as well as the following: 


string }0 If rlevel is nonzero, this string contains the “heading mark”. Two unpaddable spaces (to 
separate the mark from the heading) have been appended to this string. If rlevelis 0, this 
string is null. 


register ;0 This register indicates the type of spacing that is to follow the heading {4.2.2.2}. A value 
of 0 means that the heading is run-in. A value of 1 means a break (but no blank line) is 
to follow the heading. A value of 2 means that a blank line (one-half a vertical space) is 
to follow the heading. 


string }2 If “register ;0” is 0, this string contains two unpaddable spaces that will be used to separate 
the (run-in) heading from the following text. If “register ;0” is nonzero, this string is null. 


register ;3 This register contains an adjustment factor for a .ne request issued before the heading 
is actually printed. On entry to .HX, it has the value 3 if dlevel equals 1, and 1 otherwise. 
The .ne request is for the following number of lines: the contents of the “register ;0” taken 
as blank lines (halves of vertical space) plus the contents of “register 33” as blank lines 
(halves of vertical space) plus the number of lines of the heading. 


The user may alter the values of {0, }2, and ;3 within .HX. The following are examples of actions that might 
be performed by defining .HX to include the lines shown: 


e Change first-level heading mark from format u. to n.0: 
if \\$1=1 .ds }0\\n(H1.0\<sp>\<sp> 
(where <sp> stands for a space) 


e Separate run-in heading from the text with a period and two unpaddable spaces: 
if \\n(;0=0 .ds} 2 .\<sp>\<sp> 


e Assure that at least 15 lines are left on the page before printing a first-level heading: 
if \\$1=1 .nr 33 15-\\n(;0 


e Add three additional blank lines before each first-level heading: 
if \\$1=1 .sp 3 


e Indent level 3 run-in headings by five spaces: 
if \\ $1=8 .ti 5n 


If temporary strings or macros are used within .HX, their names should be chosen with care {14.1}. 


When the .HY macro is called after the .ne is issued, certain features requested in .HX must be repeated. 
For example: 


.de HY 
if \\$1=3 .ti 5n 
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The .HZ macro is called at the end of .H to permit user-controlled actions after the heading is produced. 
In a large document, sections may correspond to chapters of a book; and the user may want to change a page 
header or footer, e.g.: 


de HZ 
Af \\$1=1 .PF " Section \\$3" 
4.7 Hints for Large Documents 

A large document is often organized for convenience into one input text file per section. If the files are num- 
bered, it is wise to use enough digits in the names of these files for the maximum number of sections, i.e., use 
suffix numbers 01 through 20 rather than 1 through 9 and 10 through 20. 

Users often want to format individual sections of long documents. To do this with the correct section num- 
bers, it is necessary to set register HH] to one less than the number of the section just before the corresponding 
-H\ 1 call. For example, at the beginning of Part 5, insert 

.nr H1 4 


Note: This is not good practice. It defeats the automatic (re)numbering of sections when sections 
are added or deleted. Such lines should be removed as soon as possible. 


5. Lists 

This part describes different styles of lists; automatically numbered and alphabetized lists, bullet lists, dash 
lists, lists with arbitrary marks, and lists starting with arbitrary strings, i.e., with terms or phrases to be de- 
fined. 
5.1 List Macros 

In order to avoid repetitive typing of arguments to describe the style or appearance of items in a list, MM 
provides a convenient way to specify lists. All lists share the same overall structure and are composed of the 


following basic parts: 


e A list-initialization macro(.AL .BL, .DL, .ML, .RL, or .VL) determines the style of list: line spacing, in- 
dentation, marking with special symbols, and numbering or alphabetizing of list.items. 


e One or more list-item macros (.LI) identifies each unique item to the system. It is followed by the actual 
text of the corresponding list item. 


e The Jist-end macro (.LE) identifies the end of the list. It terminates the list and restores the previous 
indentation. 


Lists may be nested up to six levels. The list-initialization macro saves the previous list status (indentation 
marking style, etc.); the .LE macro restores it. 


With this approach, the format of a list is specified only once at the beginning of the list. In addition by 
building onto the existing structure, users may create their own customized sets of list macros with relatively 
little effort ({5.3} and {5.4}). 


5.1.1 List-Initialization Macros 


List-initialization macros are implemented as calls to the more basic .LB macro {5.2}. 
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They are: 

AL Automatically Numbered or Alphabetized List 

-BL Bullet List . 

.DL Dash List 

-.ML Marked List 

-RL Reference List 

.VL Variable-Item List 


5.1.1.1 Automatically Numbered or Alphabetized List 
.AL [type] [text-indent] [1] 


The .AL macro is used to begin sequentially numbered or alphabetized lists. If there are no arguments, the 
list is numbered; and text is indented by Li(initially six) spaces from the indent in force when the .AL is called. 
This leaves room for a space, two digits, a period, and two spaces before the text. Values that specify indentation 
must be unsealed and are treated as “character positions”, i.e., number of ens. 


Spacing at the beginning of the list and between items can be suppressed by setting the list space register 
(Ls). The Ls register is set to the innermost list level for which spacing is done. For example: 


nr Ls 0 


specifies that no spacing will occur around any list items. The default value for Lsis six (which is the maximum 
list nesting level). 


e The type argument may be given to obtain a different type of sequencing. Its value indicates the first 
element in the sequence desired. If type argument is omitted or null, the value 1 is assumed. 


ARGUMENT INTERPRETATION 
1 Arabic (default for all levels) 
A Uppercase alphabetic 
a Lowercase alphabetic 
I Uppercase Roman 
i Lowercase Roman 


e If text-indent argument is non-null, it is used as the number of spaces from the current indent to the 
text, i.e., it is used instead of Li for this list only. If text-indent argument is null, the value of Li will 
be used. 


e Ifthe third argument is given, a blank line (one-half a vertical space) will not separate items in the list. 
A blank line will occur before the first item however. 


5.1.1.2 Bullet List 
.BL [text-indent] [1] 
The .BL macro begins a bullet list. Each list item is marked by a bullet (e) followed by one space. 
e If the text-indent argument is non-null, it overrides the default indentation (the amount of paragraph 


indentation as given in the Pi register {4.1}). In the default case, the text of bullet and dash lists lines 
up with the first line of indented paragraphs. 
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e If the second argument is specified, no blank lines will separate items in the list. 
5.1.1.3 Dash List 
.DL [text-indent] [1] 
The .DL macro is identical to .BL except that a dash is used as the list item mark instead of a bullet. 
5.1.1.4 Marked List 
.ML mark [text-indent] [1] 


The .ML macro is much like .BL and .DL macros but expects the user to specify an arbitrary mark which 
may consist of more than a single character. 


e Text is indented text-indent spaces if the second argument is not null; otherwise, the text is indented 
one more space than the width of mark. 


e If the third argument is specified, no blank lines will separate items in the list. 


Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified {3.3}. 


5.1.1.5 Reference List 
-RL [text-indent] [1] 


A.RL macro call begins an automatically numbered list in which the numbers are enclosed by square brack- 


ets ([ ]). 

e If the text-indent argument is non-null, it is used as the number of spaces from the current indent to 
the text, i.e., it is used instead of Lifor this list only. If the text-indent argument is omitted or null, 
the value of Liis used. 

e If the second argument is specified, no blank lines will separate the items in the list. 

5.1.1.6 Variable-Item List 
.VL text-indent [mark-indent] [1] 


When a list begins with a.VL macro, there is effectively no current mark; it is expected that each .LI will 
provide its own mark. This form is typically used to display definitions of terms or phrases. 


e Text-indent provides the distance from current indent to beginning of the text. 


e Mark indent produces the number of spaces from current indent to beginning of the mark, and it de- 
faults to 0 if omitted or null. 


e If the third argument is specified, no blank lines will separate items in the list. 
An example of .VL macro usage is shown below: 


tra 
.VL 20 2 
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-LI markal 

Here is a description of mark 1; 

“mark 1” of the .LI line contains a tilde 

translated to an unpaddable space in order 

to avoid extra spaces between 

“mark” and “1” {3.3}. 

.LI secondsmark. 

This is the second mark also using a tilde translated to an unpaddable space. 

.LI thirdamarkalongerathan+indent: 

This item shows the effect of a long mark; one space separates the mark from the text. 
«LI « 

This item effectively has no mark because the tilde following the .LI is translated into a space. 
«LE 


when formatted yields: 


mark 1 Here is a description of mark 1; “mark 1” of the .LI line contains a tilde translated to 
an unpaddable space in order to avoid extra spaces between “mark” and “1” {3.3}. 


second mark This is the second mark also using a tilde translated to an unpaddable space. 


third mark longer than indent: This item shows the effect of a long mark; one space separates the mark 
from the text. 


This item effectively has no mark because the tilde following the .LI is translated into 
a space. 


The tilde argument on the last .LI above is required; otherwise, a “hanging indent” would have been pro- 
duced. A “hanging indent” is produced by using .VL and calling .LI with no arguments or with a null first argu- 
ment. For example: 


.VL 10 

LI 

Here is some text to show a hanging indent. 
The first line of text is at the left margin. 
The second is indented 10 spaces. 

LE 


when formatted yields: 


Tere is some text to show a hanging indent. The first line of text is at the left margin. The second is 
indented 10 spaces. 


Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified {3.3}. 


5.1.2 List-ltem Macro 


LI [mark] [1] 
one or more lines of text that make up the list item. 


The .LI macro is used with all lists and for each list item. It normally causes output of a single blank line 
(one-half a vertical space) before its list item although this may be suppressed. 


e If no arguments are given, .LI labels the item with the current mark which is specified by the most re- 
cent list-initialization macro. 
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e If a single argument is given, that argument is output instead of the current mark. 


e If two arguments are given, the first argument becomes a prefix to the current mark thus allowing the 
user to emphasize one or more items in a list. One unpaddable space is inserted between the prefix and 
the mark. 


For example: 


LI 

This is a simple bullet item. 

.LI + 

This replaces the bullet with a “plus”. 
LEA 

This uses a “plus” as prefix to the bullet. 
ae 


when formatted yields: 
e This is a simple bullet item. 
+ This replaces the bullet with a “plus”. 
+ e This uses “plus” as prefix to the bullet. 


Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified {3.3}. 


If the current mark (in the current list) is a null string and the first argument of .LI is omitted or null, the 
resulting effect is that of a “hanging indent”, i.e., the first line of the following text is moved to the left starting 
at the same place where mark would have started {5.1.1.6}. 


5.1.3 List-End Mocre 
-LE [1] 


The .LE macro restores the state of the list to that existing just before the most recent list-initialization 
macro call. If the optional argument is given, the .LE outputs a blank line (one-half a vertical space). This option 
should generally be used only when the .LE is followed by running text but not when followed by a macro that 
produces blank lines of its own such as the .P, .H, or .LI macro. 


The .H and .HU macros automatically clear all list information. The user may omit the .LE macros that 
would normally occur just before either of these macros and not receive the “LE:mismatched” error message. 
Such a practice is not recommended because errors will occur if the list text is separated from the heading at 
some later time (e.g., by insertion of text). 


5.1.4 Example of Nested Lists 


An example of input for the several lists and the corresponding output is shown below. The .AL and .DL 
macro calls {5.1.1} contained therein are examples of list-initialization macros. Input text is: 


ALA 
Ll 
This is alphabetized list item A. 
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ISSUE 1 


This text shows the alignment of the second line 

of the item. 

Notice the text indentations and alignment of left 
and right margins. 

AL 

LI 

This is numbered item 1. 

This text shows the alignment of the second line 

of the item. 

The quick brown fox jumped over the lazy dog’s back. 
-DL 

.LI 

This is a dash item. 

This text shows the alignment of the second line 

of the item. 

The quick brown fox jumped over the lazy dog’s back. 
LI +1 

This is a dash item with a “plus” as prefix. 


This text shows the alignment of the second line of the item. 


The quick brown fox jumped over the lazy dog’s back. 
.LE 

LI 

This is numbered item 2. 

.LE 

LI 

This is another alphabetized list item B. 

This text shows the alignment of the second line 

of the item. 

The quick brown fox jumped over the lazy dog’s back. 
= 
This paragraph follows a list item and is aligned with 
the left margin. 

A paragraph following a list resumes the normal line 
length and margins. 
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The output is: 


A. This is alphabetized list item A. This text shows the alignment of the second line of the 
item. Notice the text indentions and alignment of left and right margins. 
1. This is numbered item 1. This text shows the alignment of the second line of the 
item. The quick brown fox jumped over the lazy dog’s back. 


- This is a dash item. This text shows the alignment of the second line of the 
item. The quick brown fox jumped over the lazy dog’s back. 


+ - This is a dash item with a “plus” as prefix. This text shows the alignment 
of the second line of the item. The quick brown fox jumped over the lazy 
dog’s back. 


2. This is numbered item 2. 


B. This is another alphabetized list item B. This text shows the alignment of the second line 
of the item. The quick brown fox jumped over the lazy dog’s back. 


This paragraph follows a list item and is aligned with the left margin. A paragraph following a list resumes 
the norma! line length and margins. 


5.2 List-Begin Macro and Customized Lists 


LB text-indent mark-indent pad type [mark] [LI-space]\{LB-space] 


List-initialization macros described above suffice for almost all cases. However, if necessary, the user may 
obtain more control over the layout of lists by using the basic list-begin macro (.LB). The .LB macro is used 
by the other list-initialization macros. Its arguments are as follows: 


e The text-indent argument provides the number of spaces that text is to be indented from the current 
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indent. Normally, this value is taken from the Li register (for automatic lists) or from the Pi register 
(for bullet and dash lists). 


The combination of mark-indent and pad arguments determines the placement of the mark. The mark 
is placed within an area (called mark area) that starts mark-indent spaces to the right of the current 
indent and ends where the text begins (i.e., ends text-indent spaces to the right of the current indent). 
The mark-indent argument is typically 0. 


Within the mark area, the mark is left justified if the pad argument is 0. If pad is a number n (greater 
than 0) then n blanks are appended to the mark; the mark-indent value is ignored. The resulting string 
immediately precedes the text. The mark is effectively right justified pad spaces immediately to the left 
of text. 


Arguments type and mark interact to control the type of marking used. If type is 0, simple marking is 
performed using the mark character(s) found in the mark argument. If type is greater than 0, automatic 
numbering or alphabetizing is done; and mark is then interpreted as the first item in the sequence to 
be used for numbering or alphabetizing, i.e., it is chosen from the set (1, A, a, I, 1) as in {5.1.1.1}. This 
is summarized in the following table . 
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type mark result 
0: omitted hanging indent 
0 string string is the mark 
>0 omitted Arabic numbering 
>0 one of: automatic numbering or 


1,A,a,I,i alphabetic sequencing 


Each nonzero value of type from one to six selects a different way of displaying the marks. The following 
table shows the output appearance for each value of type: 


VALUE APPEARANCE 
1 x 
2 x) 
3 (x) 
4 [x] 
5) <X> 
6 {x} 


where xis the generated number or letter. 


Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified {3.3}. 


e The LI-space argument gives the number of blank lines (halves of a vertical space) that should be output 
by each .LI macro in the list. If omitted, LI-space defaults to 1; the value 0 can be used to obtain compact 
lists. If LJ-space is greater than 0, the .LI macro issues a .ne request for two lines just before printing 
the mark. 


e The LB-space argument is the number of blank lines (one-half a vertical space) to be output by .LB itself. 
If omitted LB-space defaults to 0. 


There are three combinations of LI-space and LB-space: 


e The normal case is to set LI-space to 1 and LB-space to 0 yielding one blank line before each item in 
the list; such a list is usually terminated with a .LE 1 macro to end the list with a blank line. 


e For a more compact list, LJ-space is set to 0, LB-space is set to 1, and the .LE 1 macro is used at the 
end of the list. The result is a list with one blank line before and after it. 


e If both LI-space and LB-space are set to 0 and the .LE macro is used to end the list, a list without any 
blank lines will result. 


Paragraph {5.3} shows how to build upon the supplied list of macros to obtain other kinds of lists. 
5.3 User-Defined List Structures 
Note: This part is intended only for users accustomed to writing formatter macros. 


If a large document requires complex list structures, it is useful to define the appearance for each list level 
only once instead of having to define the appearance at the beginning of each list. This permits consistency of 
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style in a large document. A generalized list-initialization macro might be defined in such a way that what the 
macro does depends on the list-nesting level in effect at the time the macro is called. Levels 1 through 5 of the 
lists to be formatted may have the following appearance: 


(1) 


a) 
+ 


The following code defines a macro (.aL) that always begins a new list and determines the type of list accord- 
ing to the current list level. To understand it, the user should know that the number register :gis used by the 
MM list macros to determine the current list level; it is 0 if there is no currently active list. Each eall to a list- 
initialization macro increments :g, and each .LE call decrements it. 


\"" register g is used as a local temporary to save 
\"" :g before it is changed below 


de aL 

nr g \\n(:‘g 

if \\ng=0 .AL A \" produces an A. 
if \\ng=1 .LB \\n(Li 01 4 \" produces a [1] 

Af \\ng=2 .BL \" produces a bullet 


if \\ng=3 .LB \\n(Li 0 22a \"" produces an a) 


wif \\ng=4 .ML + \" produces a 4 


This macro can be used (in conjunction with .LI and .LE) instead of .AL, .RL, .BL, .LB, and .ML. For example, 
the following input: 


aL 

LI 

First line. 
aL 

LI 

Second line. 
AY 

LI 

Third line. 
.LE 


when formatted yields 
A. First line. 
[1] Second line. 


B. Third line. 
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There is another approach to lists that is similar to the LH mechanism. List-initialization, as well as the 
-LI and the .LE macros, are all included in a single macro. That macro (defined as .bL below) requires an argu- 
ment to tell it what level of item is required; it adjusts the list level by either beginning a new list or setting 
the list level back to a previous value, and then issues a .LI macro call to produce the item. 


.de bL 
ie \\n(.$ .nr g \\$1 \"if there is an argument, 
© ; \" that is the level 
el nr g \\n(g \"if no argument, use current level 
jf \\ng—\\nCg>1 .)D \" **TLLEGAL SKIPPING OF LEVEL 


: \" increasing level by more than 1 
if \\ng>\\n(-g \{aL \\ng-1 \"if g > :g, begin new list 


nr \" and reset g to current level 

: \" (aL changes g) 

Af \\n(:g>\\ng .LC \\ng \"if :g > g, prune back to 
& , \" correct level 


\"if :g = g, stay within 
. \" current list 
LI \"in all cases, get out an item 


For .bL to work, the previous definition of the .aL macro must be changed to obtain the value of g from its 
argument rather‘than from :g. Invoking .bL without arguments causes it to stay at the current list level. The 
.LC (List Clear) macro removes list descriptions until the level is less than or equal to that of its argument. For 
example, the .H macro includes the call “.LC 0”. If text is to be resumed at the end of a list, insert the eall “LC 
0” to clear out the lists completely. The example below illustrates the relatively small amount of input needed 
by this approach. The input text 


& The quick brown fox jumped over the lazy dog’s back. 
-bL 1 
First line. 
-bL 2 
Second line. 
-bL 1 
Third line. 
-bL 
Fourth line. 
.LC 0 
Fifth line. 


& when formatted yields 


“The quick brown fox jumped over the lazy dog’s back. 
A. First line. 
[1] Second line. 


& B. Third line. 


C. Fourth line. 
Fifth line. 
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6. Memorandum and Released-Paper Style Documents 


One use of MM is for the preparation of memoranda and released-paper documents (a documentation style 
used by Bell Laboratories, Inc.) which have special requirements for the first page and for the cover sheet. Data 
needed (title, author, date, case numbers, etc.) is entered the same for both styles; an argument to the .MT 
macro indicates which style is being used. 


6.1 Sequence of Beginning Macros 
Macros, if present, must be given in the following order: 


.ND new-date 

TL [charging-case] [filing-case] 
one or more lines of text 

.AF [company-name] 

AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] 
AT [title] ... 

.TM [number] ... 

.AS [arg] [indent] 

one or more lines of text 

AE 

.NS [arg] 

one or more lines of text 

NE 

.OK [keyword] ... 

.MT [type] [addressee] 


The only required macros for a memorandum for file or a released-paper document are TL, .-AU, and .MT; 
all other macros (and their associated input lines) may be omitted if the features are not needed. Once .MT has 
been invoked, none of the above macros (except .NS and .NE) can be reinvoked because they are removed from 
the table of defined macros to save memory space. 


If neither the memorandum nor released-paper document style is desired, the TL, AU, TM, AE, OK, MT, 
ND, and AF macros should be omitted from the input text. If these macros are omitted, the first page will have 
only the page header followed by the body of the document. 


6.2 Title 


.TL [charging-case] [filing-case] 
one or more lines of title text 


Arguments to the .TL macro are the charging-case number(s) and filing-case number(s). 


e The charging-case argument is the case number to which time was charged for the development of the 
project described in the memorandum. Multiple charging - case numbers are entered as “subarguments” 
by ‘separating each from the previous with a comma and a space and enclosing the entire argument 
within double quotes. 


e The filing-case argument is a number under which the memorandum is to be filed. Multiple filing case 
members are entered similarly. For example: 


TL “12345,67890°987654321 
Construction of a Table of all Even Prime numbers 


The title of the memorandum or released-paper document follows the .TL macro and is processed in fill mode. 
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The .br request may be used to break the title into several lines as follows: 


.TL 12345 

First Title Line 
.br 

\Lbr 

Second Title Line 


On output, the title appears after the word “subject” in the memorandum style and is centered and bold 
in the released-paper document style. 


If only a charging case number or only a filing case number is given, it will be separated from the title in 
the memorandum style by a dash and will appear on the same line as the title. If hoth case numbers are given 
and are the same, then “Charging and Filing Case” followed by the number will appear on a line following the 
title. If the two case numbers are different, separate lines for “Charging Case” and “File Case” will appear after 
the title. 


6.3 Authors 
} 
-AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] 
.AT [title] ... 


The .AU macro receives as arguments information that describes an author. If any argument contains 
blanks, that argument must be enclosed within double quotes. The first six arguments must appear in the order 
given. A separate .AU macro is required for each author. 


The .AT macro is used to specify the author’s title. Up to nine arguments may be given. Each will appear 
in the signature block for memorandum style {6.11} on a separate line following the signer’s name. The .AT must 
immediately follow the .AU for the given author. For example: 


AU" J. J. Jones" JJJ PY 9876 5432 17-234 
.AT Director " Materials Research Laboratory " 


In the “from” portion in the memorandum style, the author’s name is followed by location and department 
number on one line and by room number and extension number on the next. The “x” for the extension is added 
automatically. Printing of the location, department number, extension number, and room number may be sup- 
pressed on the first page of a memorandum by setting the register Au to 0; the default value for Avis 1. Argu- 
ments 7 through 9 of the .AU macro, if present, will follow this normal author information in the “from” portion, 
each on a separate line. These last three arguments may be used for organizational numbering schemes, etc. 
For example: 


AU "S. P. Lename" SPL IH 9988 7766 5H-444 9876-543210.01MF 


The name, initials, location, and department are also used in the signature block. Author information in 


the “from” portion, as well as names and initials in the signature block will appear in the same order as the 


-AU macros. 

Names of authors in the released-paper style are centered below the title. Following the name of the last 
author, “Bell Laboratories” and the location are centered. The paragraph on memorandum types {6.7} contains 
information regarding authors from different locations. 

6.4 TM Numbers 
-TM [number] ... 


If the memorandum is a technical memorandum, the TM numbers are supplied via the .TM macro. Up to 
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nine numbers may be specified. For example: 
-TM 7654321 77777777 
This macro call is ignored in the padibiepabe: and external-letter styles {6.7}. 
6.5 Abstract 
.AS [arg] [indent] 
text of abstract 


.AE 


If a memorandum has an abstract, the input is identified with the .AS (abstract start) and .AE (abstract 
end) delimiters. Abstracts are printed on page 1 of a document and/or on its cover sheet. There are three styles 
of cover sheet: 


e released paper 
e technical memorandum 
e memorandum for file {10.2} (also used for engineer’s notes, memoranda for record, etc.). 


Cover sheets for released papers and technical memoranda are obtained by invoking the .CS macro {10.2}. 


In released-paper style (first argument of the MT macro {6.7} is 4) and in technical memorandum style if 
the first argument of .AS is: 


0 Abstract will be printed on page 1 and on the cover sheet (if any). 
1 Abstract will appear only on the cover sheet (if any). 


In memoranda for file style and in all other documents (other than external letters) if the first argument of 
AS is: 


0 Abstract will appear on page 1 and there will be no cover sheet printed. 


2 Abstract will appear only on the cover sheet which will be produced automatically (i.e., without in- 
voking the .CS macro). 


It is not possible to get either an abstract or a cover sheet with an external letter (first argument of the .MT 
macro is 5). 


Notations such as a “copy to” list {6.11} are allowed on memorandum for file cover sheets; the .NS and .NE 
macros must appear after the .AS 2 and .AE macros. Headings {4.2, 4.3} and displays {7} are not permitted within 
an abstract. 


The abstract is printed with ordinary text margins; an indentation to be used for both margins can be speci- 
fied as the second argument of .AS. Values that specify indentation must be unscaled and are treated as “charac- 
ter positions”, i.e., as the number of ens. 


6.6 Other Keywords 
.OK [keyword] ... 
Topical keywords should be specified on a technical memorandum cover sheet. Up to nine such keywords 


or keyword phrases may be specified as arguments to the .OK macro; if any keyword contains spaces, it must 
be enclosed within double quotes. 
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6.7 Memorandum Types 
.MT [type] [addressee] 


The .MT macro controls the format of the top part of the first page of a memorandum or of a released-paper 
document and the format of the cover sheets. The type arguments and corresponding values are: 


type Value 


me 


no memorandum type printed 


0 no memorandum type printed 
none MEMORANDUM FOR FILE 
1 MEMORANDUM FOR FILE 
2 PROGRAMMER’S NOTES 

3 ENGINEER’S NOTES 

4 released-paper style 

5 external-letter style 

" string" string (enclosed in quotes) 


If the type argument indicates a memorandum style document, the corresponding statement indicated 
under “Value” will be printed after the last line of author information. If typeis longer than one character, then 
the string itself will be printed. For example: 

.MT " Technical Note /5" 
A simple letter is produced by calling .MT with a null (but not omitted) or 0 argument. 


The second argument to .MT is the name of the addressee of a letter. If present, that name and the page 
number replace the normal page header on the second and following pages of a letter. For example: 


.MT 1" John Jones" 
produces 
John Jones — 2 
The addressee argument may not be used if the first argument is 4 (released-paper style document). 
The released-paper style is obtained by specifying 
MT 4 [1] 
This results in a centered, bold title followed by centered names of authors. The location of the last author is 


used as the location following “Bell Laboratories” (unless the .AF macro specifies a different company). If the 
optional second argument to .MT 4 is given, then the name of each author is followed by the respective company 
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name and location. Information necessary for the memorandum style document but not for the released-paper 
style document is ignored. 


If the released-paper style document is utilized, most BTL location codes are defined as strings that are the 
addresses of the corresponding BTL locations. These codes are needed only until the .MT macro is invoked. Thus, 
following the .MT macro, the user may reuse these string names. In addition, the macros for the end of a memo- 
randum {6.11} and their associated lines of input are ignored when the released-paper style is specified. 


Authors from non-BTL locations may include their affiliations in the released-paper style by specifying the 
appropriate .AF macro {6.9} and defining a string (with a 2-character name such as ZZ) for the address before 
each .AU. For example: 


TL 

A Learned Treatise 

AF " Getem Inc." 

.ds ZZ" 22 Maple Avenue, Sometown 09999" 
AU" F. Swatter" "" ZZ 

.AF " Bell Laboratories" 

.AU "Sam P. Lename" "" CB 

MT 41 


In the external-letter style document (.MT 5), only the title (without the word “subject:”) and the date are 
printed in the upper left and right corners, respectively, on the first page. It is expected that preprinted statio- 
nery will be used with the company logo and address of the author. 


6.8 Date Changes 
.ND new-date 


The .ND macro alters the value of the string DT, which is initially set to produce the current date. If the 
argument contains spaces, it must be enclosed within double quotes. 


6.9 Alternate First-Page Format 
.AF [company-name] 


An alternate first-page format can be specified with the .AF macro. The words “subject”, “date”, and 
“from” (in the memorandum style) are omitted and an alternate company name is used. 


If an argument is given, it replaces “Bell Laboratories” without affecting other headings. If the argument 
is null, “Bell Laboratories” is suppressed; and extra blank lines are inserted to allow room for stamping the doc- 
ument with a Bell System logo or a Bell Laboratories stamp. 


The .AF with no argument suppresses “Bell Laboratories” and the “Subject/Date/From” headings, thus 
allowing output on preprinted stationery. The use of .AF with no arguments is equivalent to the use of —rA1 
{2.4}, except that the latter must be used if it is necessary to change the line length and/or page offset (which 
default to 5.8i and i, respectively, for preprinted forms). The command line options —rOk and —rWk {2.4} are 
not effective with .AF. The only .AF use appropriate for the troff formatter is to specify a replacement for “Bell 
Laboratories”. 


The command line option —rEn {2.4} controls the font of the “Subject/Date/From” block. 
6.10 Example 


Input text for a document may begin as follows: 


TL 
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MM\*(EMMemorandum Macros 

AU "D. W. Smith" DWS PY 

.AU"J. R. Mashey" JRM PY 

-AU"E. C. Pariser (January 1980 Revision)" ECP PY 
AU "N. W. Smith (June 1980 Revision)" NWS PY 
.MT 4 


Figure 4.1 shows the input text file and both the nroff and troff formatter outputs for a simple letter. 


6.11 End of Memorandum Macros 


At the end of a memorandum document (but not of a released-paper document), signatures of authors and 
a list of notations can be requested. The following macros and their input are ignored if the released-paper style 
document is selected. 


6.11.1 Signature Block 


.FC [closing] 
SG [arg] [1] 


The .FC macro prints “Yours very truly,” as a formal closing, if no argument is used. It must be given before 
the .SG macro. A different closing may be specified as an argument to .FC. 


The .SG macro prints the author’s name(s) after the formal closing, if any. Each name begins at the center 
of the page. Three blank lines are left above each name for the actual signature. 


e If no arguments are given, the line of reference data (location code, department number, author’s ini- 
tials, and typist’s initials, all separated by hyphens) will not appear. 


e A non-null first argument is treated as the typist’s initials and is appended to the reference data. 
e A null first argument prints reference data without the typist’s initials or the preceding hyphen. 


e If there are several authors and if the second argument is given, reference data is placed on the line 
of the first author. 


Reference data contains only the location and department number of the first author. Thus, if there are au- 
thors from different departments and/or from different locations, the reference data should be supplied manu- 
ally after the invocation (without arguments) of the SG macro. For example: 


SG 

TS 

sp -lv 
PY/MH-9876/5432-JJJ/SPL-cen 


6.11.2 “Copy to” and Other Notations 
-NS [arg] 


zero or more lines of the notation 
NE 


Many types of notations (such as a list of attachments or “Copy to” lists) may follow signature and reference 


data. Various notations are obtained through the .NS macro, which provides for proper spacing and for break- 
ing notations across pages, if necessary. 
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Codes for arg and the corresponding notations are: 


arg Notations 


none Copy to 
sis Copy to 
Copy to 
Copy (with att.) to 
Copy (without att.) to 
Att. 
Atts. 
Ene. 
Encs. 
Under Separate Cover 
Letter to 
Memorandum to 
string" Copy (string) to 


caonananhwoNnr & 


If arg consists of more than one character, it is placed within parentheses between the words “Copy” and 
“to”, For example: 


NS" with att. 1 only" 
will generate 
Copy (with att. 1 only) to 


as the notation. More than one notation may be specified before the .NE macro because a .NS5 macro terminates 
the preceding notation, if any. For example: 


.NS 4 

Attachment 1-List of register names 
Attachment 2-List of string and macro names 
NS 1 

J. J. Jones 

.NS 2 

S. P. Lename 

G. H. Hurtz 

NE 


would be formatted as 


Atts. 
Attachment 1—List of register names 
. Attachment 2—List of string and macro names 


Copy (with att.) to 
J. J. Jones 


Copy (without att.) to 
5. P. Lename 
G. H. Hurtz 


The .NS and .NE macros may also be used at the beginning following .AS 2 and .AF to place the notation 
list on the memorandum for file cover sheet {6.5}. If notations are given at the beginning without .AS 2, they 
will be saved and output at the end of the document. 
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6.11.3 Approval Signature Line 
-AV approver’s-name . 


The .AV macro may be used after the last notation block to automatically generate a line with spaces for 
the approval signature and date. For example: 


.AV "Jane Doe" 
produces 
APPROVED: 
Jane Doe Date 


6.12 One-Page Letter 


At times, the user may like more space on the page forcing the signature or items within notations to the 
bottom of the page so that the letter or memo is only one page in length. This can be accomplished by increasing 
the page length with the —rLa option, e.g., ~rL90. This has the effect of making the formatter believe that the 
page is 90 lines long and therefore providing more space than usual to place the signature or the notations. 


Note: This will work only for a single-page letter or memo. 
7. Displays 


Displays are blocks of text that are to be kept together on a page and not split across pages. They are pro- 
cessed in an environment that is different from the body of the text (see the .ev request). The MM package pro- 
vides two styles of displays—a static (.DS) style and a floating (.DF) style. 


e In the static style, the display appears in the same relative position in the output text as it does in the 
input text. This may result in extra white space at the bottom of the page if the display is too long to 
fit in the remaining page space. 


e In the floating style, the display “floats” through the input text to the top of the next page if there is 
not enough space on the current page. Thus input text that follows a floating display may precede it 
in the output text. A queue of floating displays is maintained so that their relative order of appearance 
in the text is not disturbed. 


By default, a display is processed in no-fill mode with single spacing and is not indented from the existing 
margins. The user can specify indentation or centering as well as fill-mode processing. 


Note: Displays and footnotes {8} may never be nested in any combination. Although lists {5} and para- 
graphs {4.1} are permitted, no headings (.H or .HU) {4.2, 4.3} can occur within displays or footnotes. 


7.1 Static Displays 


.DS [format] [fill] [rindent] 
one or more lines of text 


.DE 
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A static display is started by the .DS macro and terminated by the .DE macro. With no arguments, .DS 
accepts lines of text exactly as typed (no-fill mode) and will not indent lines from the prevailing left margin 
indentation or from the right margin. 


e The format argument is an integer or letter used to control the left margin indentation and centering 
with the following meanings: 


format Meaning 

aa! no indent 

Oor L no indent 

lorl indent by standard amount 
2 or C center each line 

3 or CB center as a block. 

omitted no indent 


e The fill argument is an integer or letter and can have the following meanings: 
fill Meaning 


ie no-fill mode 
OorN no-fill mode 
lorF fill mode 

omitted no-fill mode 


e The rindent argument is the number of characters that the line length should be decreased, i.e., an in- 
dentation from the right margin. This number must be unscaled in the nroff formatter and is treated 
as ens. It may be scaled in the troff formatter or else defaults to ems. 


The standard amount of static display indentation is taken from the Siregister, a default value of five spac- 
es. Thus, text of an indented display aligns with the first line of indented paragraphs, whose indent is contained 
in the Pi register {4.1}. Even though their initial values are the same (default values), these two registers are 
independent. 


The display format argument value 3 (or CB) centers (horizontally) the entire display as a block (as opposed 
to .DS 2 and .DF 2 which center each line individually). All collected lines are left justified, and the display is 
centered based on width of the longest line. This format must be used in order for the eqn/neqn “mark” and 
“lineup” feature to work with centered equations {7.4}. 


By default, a blank line (one-half a vertical space) is placed before and after static and floating displays. 
These blank lines before and after static displays can be inhibited by setting the register Ds to 0. 


The following example shows usage of all three arguments for static displays. This block of text will be in- 
dented five,spaces from the left margin, filled, and indented five spaces from the right margin (i.e., centered). 
The input text 


DSIF5 

‘“‘We the people of the United States, 

in order to form a more perfect union, | 
establish justice, ensure domestic tranquillity, 
provide for the common defense, 

and secure the blessings of liberty to 

ourselves and our posterity, 

do ordain and establish this Constitution for the 
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United States of America.” 
.DE 


produces 


“We the people of the United States, in order to form a more perfect union, establish justice, 
ensure domestic tranquillity, provide for the common defense, and secure the blessings of liberty 
to ourselves and our posterity, do ordain and establish this Constitution to the United States of 
America.” 


7.2 Floating Displays 


.DF [format] [fill] [rindent] 
one or more lines of text 
.DE 


A floating display is started by the .DF macro and terminated by the .DE macro. Arguments have the same 
meanings as static displays described above, except indent, no indent, and centering are calculated with respect 
to the initial left'‘margin. This is because prevailing indent may change between the time the formatter first 
reads the floating display and when the display is printed. One blank line (one-half a vertical space) occurs be- 
fore and after a floating display. 


The user may exercise precise control over the output positioning of floating displays through the use of 
two number registers, De and Df (see below). When a floating display is encountered by the nroff or troff 
formatter, it is processed and placed onto a queue of displays waiting to be output. Displays are removed from 
the queue and printed in the order entered, which is the order they appeared in the input file. If a new floating 
display is encountered and the queue of displays is empty, the new display is a candidate for immediate output 
on the current page. Immediate output is governed by size of display and the setting of the Df register code. 
The De register code controls whether text will appear on the current page after a floating display has been 
produced. 


As long as the display queue contains one or more displays, new displays will be automatically entered there, 
rather than being output. When a new page is started (or the top of the second column when in 2-column mode), 
the next display from the queue becomes a candidate for output if the Df register code has specified “top-of- 
page” output. When a display is output, it is also removed from the queue. 


When the end of a section (using section-page numbering) or the end of a document is reached, all displays 


are automatically removed from the queue and output. This occurs before a .SG, .CS, or .TC macro is processed. 
’ p 


A display will fit on the current page if there is enough room to contain the entire display or if the display 
is longer than one page in length and less than half of the current page has been used. A wide (full-page width) 
display will not fit in the second column of a 2-column document. 


The De and Df number register code settings and actions are as follows: 
De Register 
CODE ACTION 


0 No special action occurs (also the default condition). 


Page 195 


DOCUMENT PROCESSING GUIDE ISSUE 1 6/82 


CODE ACTION 


iL A page eject will always follow.the output of each floating display, so only one floating display 
will appear on a page and no text will follow it. 


Note: For any other code, the action performed is the same as for code 1. 


Df Register 
CODE ACTION 

0 Floating displays will not be output until end of section (when section-page numbering) or 
end of document. 

1 Output new floating display on current page if there is space; otherwise, hold it until end of 
section or document. 

2 Output exactly one floating display from queue to the top of a new page or column (when in 
2-column mode). 

3 Output one floating display on current page if there is space; otherwise, output to the top of 
a new page or column. 

4 Output as many displays as will fit (at least one) starting at the top of a new page or column. 


Note: If De register is set to 1, each display will be followed by a page eject causing a new top of page 
to be reached where at least one more display will be output (this also applies to code 5). 


5 Output a new floating display on the current page if there is room (also the default condition). 
Output as many displays (at least one) as will fit on the page starting at the top of a new page 
or column. 


Note: For any code greater than 5, the action performed is the same as for code 5. 


The .WC macro {12.4} may also be used to control handling of displays in double-column mode and to control 
the break in text before floating displays. 


7.3 Tables 


.TS [H] 

global options; 

column descriptors. 

title lines 

[.TH [N]] 

data within the table. 
STE 


The .TS (table start) and .TE (table end) macros make possible the use of the tbl(1) program. These macros 
are used to delimit text to be examined by tbl and to set proper spacing around the table. The display function 
and the tbl delimiting function are independent. In order to permit the user to keep together blocks that contain 
any mixture of tables, equations, filled text, unfilled text, and caption lines, the .TS/.TE block should be enclosed 
within a display (.DS/.DE). Floating tables may be enclosed inside floating displays (.DF/.DE). 


Macros .TS and .TE permit processing of tables that extend over several pages. If a table heading is needed 
for each page of a multipage table, the “H” argument should be specified to the .TS macro as above. Following 
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the options and format information, table title is typed on as many lines as required and is followed by the .TH 
macro. The .TH macro must occur when “.TS H” is used for a multipage table. This is not a feature of tbl but 
of the definitions provided by the MM macro package. 


The.TH (table header) macro may take as an argument the letter N. This argument causes the table header 
to be printed only if it is the first table header on the page. This option is used when it is necessary to build 
long tables from smaller .TS H/.TE segments. For example: 


.TS H 

global options; 
column descriptors. 
Title lines 

.TH 

data 

.TE 

.TS H 

global options; 
column descriptors. 
Title lines 

THN 

data 

.TE 


will cause the table heading to appear at the top of the first table segment and no heading to appear at the top 
of the second segment when both appear on the same page. However, the heading will still appear at the top 
of each page that the table continues onto. This feature is used when a single table must be broken into segments 
because of table complexity (e.g., too many blocks of filled text). If each segment had its own .TS H/.TH se- 
quence, it would have its own header. However, if each table segment after the first uses .TS H/.TH N, the table 
header will appear only at the beginning of the table and the top of each new page or column that the table con- 
tinues onto. 


For the nroff formatter, the —e option [—E for mm/(1) {2.1}] may be used for terminals, such as the 450, 
that are capable of finer printing resolution. This will cause better alignment of features such as the lines form- 
ing the corner of a box. The —e is not effective with coK1). 


7.4 Equations 


.DS 
-EQ [label] 
equation(s) 
EN 
.DE 


Mathematical typesetting programs eqn(1) and neqn expect to use the .EQ (equation start) and .EN (equa- 


‘tion end) macros as delimiters in the same way that tbl(1) uses .TS and .TE; however, .EQ and .EN must occur 


inside a .DS/.DE pair. There is an exception to this rule — if .EQ and .EN are used to specify only the delimiters 
for in-line equations or to specify eqn/neqn defines, the .DS and .DE macros must not be used; otherwise, extra 
blank lines will appear in the output. 


The .EQ macro takes an argument that will be used as a label for the equation. By default, the label will 
appear at the right margin in the “vertical center” of the general equation. The Eq register may be set to 1 to 
change labeling to the left margin. 


The equation will be centered for centered displays; otherwise, the equation will be adjusted to the opposite 
margin from the label. 
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7.5 Figure, Table, Equation, and Exhibit Titles 


FG [title] [override] [flag] 
TB [title] [override] [flag] 
.EC [title] [override] [flag] 
.EX [title] [override] [flag] 


The .FG (figure title), .TB (table title), .EC (equation caption), and .EX (exhibit caption) macros are nor- 
mally used inside .DS/.DE pairs to automatically number and title figures, tables, and equations. These macros 
use registers Fg, Tb, Ec, and Ex, respectively (see paragraph {2.4} on —rNé5 to reset counters in sections). For 
example: 


.FG " This is a Figure Title" 
yields 
Figure 1. This is a Figure Title 
The .TB macro replaces “Figure” with “TABLE”, the .EC macro replaces “Figure” with “Equation”, and 
the .EX macro replaces “Figure” with “Exhibit”. The output title is centered if it can fit on a single line; other- 


wise, all lines but the first are indented to line up with the first character of the title. The format of the numbers 
may be changed using the .af request of the formatter. The format of the caption may be changed from 


Figure 1. Title 
to 
Figure 1—Title 
by setting the Of register to 1. 
The override argument is used to modify normal numbering. If flag argument is omitted or 0, override is 
used as a prefix to the number; if the flag argument is 1, override is used as a suffix; and if the flag argument 
is 2, override replaces the number. If -rN5 {2.4} is given, “section-figure” numbering is set automatically and 


user-specified override string is ignored. 


As a matter of formatting style, table headings are usually placed above the text of tables, while figure, 
equation, and exhibit titles are usually placed below corresponding figures and equations. 


7.6 List of Figures, Tables, Equations, and Exhibits 


A list of figures, tables, exhibits, and equations are printed following the table of contents if the number 
registers Lf Lt, Lx, and Le (respectively) are set to 1. The Lf, Lt, and Lx registers are 1 by default; Leis 0 by 
default. 


Titles of these lists may be changed by redefining the following strings which are shown here with their 
default values: 


.ds Lf LIST OF FIGURES 
.ds Lt LIST OF TABLES 

.ds Lx LIST OF EXHIBITS 
.ds Le LIST OF EQUATIONS 
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8. Footnotes 


There are two macros (.F'S and .FE) that delimit text of footnotes, a string that automatically numbers foot- 
notes, and a macro (.F'D) that specifies the style of footnote text. Footnotes are processed in an environment 
different from that of the body of text. Refer to .ev request. 


8.1 Automatic Numbering of Footnotes 


Footnotes may be automatically numbered by typing the three characters “\*F” (i.c., invoking the string 
F) immediately after the text to be footnoted without any intervening spaces. This will place the next sequential 
footnote number (in a smaller point size) a half line above the text to be footnoted. 


8.2 Delimiting Footnote Text 


.F'S [label] 
one or more lines of footnote text 
FE 


There are two macros that delimit the text of each footnote. The .FS (footnote start) macro marks the begin- 
ning of footnote text, and the .FE (footnote end) macro marks the end. The Jahe/ on the .FS, if present, will be 
used to mark footnote text. Otherwise, the number retrieved from the string F'will be used. Automatically num- 
bered and user-labeled footnotes may be intermixed. If a footnote is labeled (.FS Jabel), the text to be footnoted 
must be followed by Jabel, rather than by “\*F”. Text between .FS and .FE is processed in fill mode. Another 
.FS, a .DS, or a .DF are not permitted between .FS and .FE macros. If footnotes are required in the title, abstract, 
or table {7.3} only labeled footnotes will appear properly, Everywhere else automatically numbered footnotes 
work correctly. For example: 


Automatically numbered footnote: 


This is the line containing the word\*F 
FS 

This is the text of the footnote. 

.FE 

to be footnoted. 


Labeled footnote: 


This is a labeled* 
FS * 


The footnote is labeled with an asterisk. 
FE 
footnote. 


Text of the footnote (enclosed within the .FS/.FE pair) should immediately follow the word to be footnoted 
in the input text, so that “\*F” or Jabel occurs at the end of a line of input and the next line is the .FS macro 
call. It is also good practice to append an unpaddable space {3.3} to “\*F” or /abel when they follow an end-of- 
sentence punctuation mark (i.e., period, question mark, exclamation point). 

Figure 4.2 illustrates the various available footnote styles as well as numbered and labeled footnotes. 


8.3 Format Style of Footnote Text 


FD [arg] [1] 
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Within footnote text, the user can control formatting style by specifying text hyphenation, right margin 
justification, and text indentation, as well as left or right justification of the label when text indenting is used. 
The .FD macro is invoked to select the appropriate style. 


The first argument is a number from the left column of the following table. Formatting style for each num- 
ber is indicated in the remaining four columns. Further explanation of the first two of these columns is given 
in the definitions of the .ad, .hy, .na, and .nh (adjust, hyphenation, no adjust, and no hyphenation, respectively) 
requests in the nroff part of this document. 


TEXT LABEL 
arg HYPHENATION ADJUST INDENT JUSTIFICATION 


0 nh cad yes left 
1 hy vad yes left 
2 nh na yes left 
3 shy na yes left 
4 nh cad no left 
5 hy vad no left 
6 nh na no left 
a -hy na no left 
8 nh vad yes right 
9 chy cad yes right 
10 nh na yes right 
1] -hy na yes right 


If the argument to .FD is greater than 11, the effect is as if “.FD 0” were specified. If the first argument 
is omitted or null, the effect is equivalent to “.FD 10” in the nroff formatter and to “.FD 0” in the troff 
formatter; these are also the respective initial default values. 


If the second argument is specified, then when a first-level heading is encountered, automatically numbered 
footnotes begin again with 1. This is most useful with the “section-page” page numbering scheme. As an exam- 
ple, the input line 


FD we 1 


maintains the default formatting style and causes footnotes to be numbered afresh after each first-level heading 
in a document. 


Hyphenation across pages is inhibited by MM except for long footnotes that continue to the following page. 
If hyphenation is permitted, it is possible for the last word on the last line on the current page footnote to be 
hyphenated. The user has control over this situation by specifying an even .FD argument. 


Footnotes are separated from the body of the text by a short line rule. Those that continue to the next page 
are separated from the body of the text by a full-width rule. In the troff formatter, footnotes are set in type 
two points smaller than the point size in the body of text. 


8.4 Spacing Between Footnote Entries 


Normally, one blank line (a 3-point vertical space) separates footnotes when more than one occurs on a page. 
To change this spacing, the F's number register is set to the desired value. For example: 


nr Fs 2 


will cause two blank lines (a 6-point vertical space) to occur between footnotes. 
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9. Page Headers and Footers 


Text printed at the top of each.page is called page header. Text printed at the bottom of each page is called 
page footer. There can be up to three lines of text associated with the header — every page, even page only, and 
odd page only. Thus the page header may have up to two lines of text — the line that occurs at the top of every 
page and the line for the even- or odd-numbered page. The same is true for the page footer. 


This part describes the default appearance of page headers and page footers and ways of changing them. 
The term header (not qualified by even or odd) is used to mean the page header line that occurs on every page, 
and similarly for the term footer. 


9.1 Default Headers and Footers 


By default, each page has a centered page number as the header. There is no default footer and no even/odd 
default headers or footers except as specified in paragraph {9.3}. 


In a memorandum or a released-paper style document, the page header on the first page is automatically 
suppressed provided a break does not occur before the .MT macro is called. Macros and text in the following 
categories do not cause a break and are permitted before the memorandum types (.MT) macro: 


e Memorandum and released-paper style document macros (.TL, .AU, .AT, .TM, .AS, .AE, .OK, .ND, .AF, 
.NS, and .NE) 


e Page headers and footers macros (.PH, .EH, .OH, .PF, .EF, and .OF) 
e The .nr and .ds requests. 
9.2 Header and Footer Macros 
For header and footer macros (.PH .EH, .OH, .PF, .EF, and .OF), the argument [arg] is of the following form: 


" left-part’center-part’right-part 


If it is inconvenient to use apostrophe (’) as the delimiter because it occurs within one of the parts, it may be 
replaced uniformly by any other character. In formatted output, the parts are left justified, centered, and right 
justified, respectively. 


9.2.1 Page Header 


-PH [arg] 


r 


The .PH macro specifies the header that is to appear at the top of every page. The initial value is the default 
centered page number enclosed by hyphens. The page number contained in the Pregister is an Arabic number. 
The format of the number may be changed by the .af macro request. 


If “debug mode” is set using the flag —rD1 on the command line {2.4}, additional information printed at the 
top left of each page is included in the default header. This consists of the Source Code Control System (SCCS) 
release and level of MM (thus identifying the current version {12.3}) followed by the current line number within 
the current input file. 


9.2.2 Even-Page Header 


-EH [arg] 
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The .EH macro supplies a line to be printed at the top of each even-numbered page immediately following 
the header. Initial value is a blank line. 

9.2.3 Odd-Page Header 
.OH [arg] 

The .OH macro is the same as the .EH except that it applies to odd-numbered pages. 

9.2.4 Page Footer 
.PF [arg] 

The .PF macro specifies the line that is to appear at the bottom of each page. Its initial value is a blank 
line. If the —rCn flag is specified on the command line {2.4}, the type of copy follows the footer on a separate 
line. In particular, if —rC3 or —rC4 (DRAFT) is specified, the footer is initialized to contain the date {6.8} instead 
of being a blank line. 

9.2.5 Even-Page Footer 


.EF [arg] 


The .EF macro supplies a line to be printed at the bottom of each even-numbered page immediately pr si 
ing the footer. Initial value is a blank line. 


9.2.6 Odd-Page Footer 
.OF [arg] 
The .OF macro is the same as .EF except that it applies to odd-numbered pages. 
9.2.7 First Page Footer 


By default, the first page footer is a blank line. If, in the input text file, the user specifies .PF and/or .OF 
before the end of the first page of the document, these lines will appear at the bottom of the first page. 


The header (whatever its contents) replaces the footer on the first page only if the —rN1 flag is specified 
on the command line {2.4}. 


9.3 Default Header and Footer With Section-Page Numbering 

Pages can be numbered sequentially within sections by “section-number page-number” {4.5}. To obtain this 
numbering style, —rN3 or —rN5 is specified on the command line. In this case, the default footer is a centered 
“section-page’ number, e.g., 7-2; and the default page header is blank. 
9.4 Strings and Registers in Header and Footer Macros 

String and register names may be placed in arguments to header and footer macros. If the value of the string 
or register is to be computed when the respective header or footer is printed, invocation must be escaped by 
four backslashes. This is because string or register invocation will be processed three times: 


1. As the argument to the header or footer macro 


2. In a formatting request within the header or footer macro 
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3. In a .tl request during header or footer processing. 


For example, page number register P must be escaped with four backslashes in order to specify a header 
in which the page number is to be printed at the right margin, e.g.: 


.PH "’”’Page \\\\nP’" 


creates a right-justified header containing the word “Page” followed by the page number. Similarly, to specify 
a footer with the “section-page” style, the user specifies (see paragraph {4.2.2.5} for meaning of H1): 


PF" \\\\n(H1-\\\\nP ~"" 


If the user arranges for the string a] to contain the current section heading which is to be printed at the 
bottom of each page, the .PF macro call would be: 


PF "”\\\\*(a)”" 


If only one or two backslashes were used, the footer would print a constant value for a], namely, its value 
when .PF appeared in the input text. 


9.5 Header and Footer Example 


The following sequence specifies blank lines for header and footer lines, page numbers on the outside margin 
of each page (i.e., top left margin of even pages and top right margin of odd pages), and “Revision 3” on the 
top inside margin of each page (nothing is specified for the center): 


Shed a 
ol El di 
.EH "’\\\\nP” Revision 3’ " 
.OH "’Revision 3”\\\\nP’" 


9.6 Generalized Top-of-Page Processing 
Note: This part is intended only for users accustomed to writing formatter macros. 
During header processing, MM invokes two user-definable macros: 
e The .TP (top of page) macro is invoked in the environment (refer to .ev request) of the header. 


e The.PX is a page header user-exit macro that is invoked (without arguments) when the normal environ- - 
ment has been restored and with the “no-space” mode already in effect. 


The effective initial definition of .TP (after the first page of a document) is 


.de TP 

sp 3 

th \\*(}t 

-if e ’tl \\*Ge 
if o ’tl \\*(o 
Sp Z 


The string }i contains the header, the string }e contains the even-page header, and the string }o contains the 
odd-page header as defined by the .PH, .EH, and .OH macros, respectively. To obtain more specialized page ti- 
tles, the user may redefine the .TP macro to cause the desired header processing {12.5}. Formatting done within 
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the .TP macro is processed in an environment different from that of the body. For example, to obtain a page 
header that includes three centered lines of data, i.e., document number, issue date, and revision date, the user 
could define the .TP as follows: 


.de TP 


Sp 

ce 3 

T7T7-888-999 

Iss. 2, AUG 1977 
Rev. 7, SEP 1977 


Sp 


The .PX macro may be used to provide text that is to appear at the top of each page after the normal header 
and that may have tab stops to align it with columns of text in the body of the document. 


9.7 Generalized Bottom-of-Page Processing 


.BS 
zero or more lines of text 
.BE 


Lines of text that are specified between the .BS (bottom-block start) and .BE (bottom-block end) macros 
will be printed at the bottom of each page after the footnotes (if any) but before the page footer. This block of 
text is removed by specifying an empty block, i.e.: 


-BS 
.BE 


The bottom block will appear on the table of contents, pages, and the cover sheet for memorandum for file, but 
not on the technical memorandum or released-paper cover sheets. 


9.8 Top and Bottom (Vertical) Margins 
.VM [top] [bottom] 
The .VM (vertical margin) macro allows the user to specify additional space at the top and bottom of the 
page. This space precedes the page header and follows the page footer. The ._VM macro takes two unscaled argu- 
ments that are treated as v’s. For example: 


-VM 10 15 


adds 10 blank lines to the default top of page margin and 15 blank lines to the default bottom of page margin. 
Both arguments must be positive (default spacing at the top of the page may be decreased by redefining .TP). 


9.9 Proprietary Marking 
.PM [code] 


The .PM (proprietary marking) macro appends to the page footer a PRIVATE, NOTICE, BELL LABORA- 
TORIES PROPRIETARY, or BELL LABORATORIES RESTRICTED disclaimer. The code argument may be: 


code _—_— Diselaimer 
none turn off previous disclaimer, if any 
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code Disclaimer 

P PRIVATE 

N NOTICE 

BP BELL LABORATORIES PROPRIETARY 
BR BELL LABORATORIES RESTRICTED 


These disclaimers are in a form approved for use by the Bell System. The user may alternate disclaimers 
by use of the .BS/.BE macro pair. 


9.10 Private Documents 
nr Pv value 


The word “PRIVATE” may be printed, centered, and underlined on the second line of a document (preceding 
the page header). This is done by setting the Pv register value: 


value Meaning 


0 do not print PRIVATE (default) 
1 PRIVATE on first page only 
2 PRIVATE on all pages 


If value is 2, the user definable .TP macro may not be used because the .TP macro is used by MM to print 
“PRIVATE” on all pages except the first page of a memorandum on which .TP is not invoked. 


10. Table of Contents and Cover Sheet 


The table of contents and the cover sheet for a document are produced by invoking the .TC and .CS macros, 
respectively. 


Note: This section refers to cover sheets for technical memoranda and released papers only. The mecha- 
nism for producing a memorandum for file cover sheet was discussed earlier {6.5} 


These macros normally appear once at the end of the document, after the Signature Block {6.11.1} and Nota- 
tions {6.11.2} macros, and may occur in either order. 


The table of contents is produced at the end of the document because the entire document must be processed 
before the table of contents can be generated. Similarly, the cover sheet may not be desired by a user and is 
therefore produced at the end. 

10.1 Table of Contents 
.TC [slevel] [spacing] [tlevel] [tab] [head1] [head2} |head3] [head4| [head5] 


The .TC macro generates a table of contents containing heading levels that were saved for the table of con- 


‘tents as determined by the value of the Cl register {4.4}. Arguments to .TC control spacing before each entry, 


placement of associated page number, and additional text on the first page of the table of contents before the 
word “CONTENTS”. 


Spacing before each entry is controlled by the first and second arguments ([s/evel] and | spacing]). Headings 
whose level is less than or equal to slevel will have spacing blank lines (halves of a vertical space) before them. 
Both slevel and spacing default to 1. This means that first-level headings are preceded by one blank line (one- 


half a vertical space). The slevel argument does not control what levels of heading have been saved; saving of 
headings is the function of the Cl register. 
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The third and fourth arguments ([tlevel] and [tab] control placement of associated page number for each 
heading. Page numbers can be justified at the right margin with either blanks or dots (called leaders) separating 
the heading text from the page number, or the page numbers can follow the heading text. 


For headings whose level is less than or equal to tlevel (default 2), page numbers are justified at the right 
margin. In this case, the value of tab determines the character used to separate heading text from page number. 
If tab is 0 (default value), dots (i.e., leaders) are used. If tab is greater than 0, spaces are used. 


For headings whose level is greater than tlevel, page numbers are separated from heading text by two spaces 
(i.e., page numbers are “ragged right”, not right justified). 


Additional arguments (| head1] ... [head4]) are horizontally centered on the page and precede the table of 
contents. 


If the .TC macro is invoked with at most four arguments, the user-exit macro .TX is invoked (without argu- 
ments) before the word “CONTENTS” is printed, or the user-exit macro .TY is invoked and the word “CON- 
TENTS” is not printed. 


By defining .TX or .TY and invoking .TC with at most four arguments, the user can specify what needs to 
be done at the top of the first page of the table of contents. For example: 


de TX 
ce 2 
Special Application 
Message Transmission 
Sp 2 
in +10n 
Approved: \I’3i’ 
in 
sp 
TC 
yields the following output when the file is formatted 


Special Application 
Message Transmission 


Approved: 
CONTENTS 


If the .TX macro were defined as .TY, the word “CONTENTS” would be suppressed. Defining .TY as an 
empty macro will suppress “CONTENTS” with no replacement: 


de TY 


By default, the first level headings will appear in the table of contents left justified. Subsequent levels will 
be aligned with the text of headings at the preceding level. These indentations may be changed by defining the 
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Ci string which takes a maximum of seven arguments corresponding to the heading levels. It must be given at 
least as many arguments as are set by the C/ register. Arguments must be scaled; for example, with “Cl = 5”: 


.ds Ci .25i .5i .75i 1i li 
or 
.ds Ci 0 2n 4n 6n 8n 


Two other registers are available to modify the format of the table of contents — Oc and Cp. By default, 
table of contents pages will have lowercase Roman numeral page numbering. If the Oc register is set to 1, the 
-TC macro will not print any page number but will instead reset the Pregister to 1. It is the user’s responsibility 
to give an appropriate page footer to specify the placement of the page number. Ordinarily, the same .PF macro 
(page footer) used in the body of the document will be adequate. 


The list of figures, tables, ete. pages will be produced separately unless Cp is set to 1, which causes these 
lists to appear on the same page as the table of contents. 


10.2 Cover Sheet 
.CS [pages] [other] [total] [figs] [tbls] [refs] 


The .CS macro generates a cover sheet in either the released paper or technical memorandum style (see 
paragraph {6.5} for details of the memorandum for file cover sheet). All other information for the cover sheet 
is obtained from data given before the .MT macro call {6.1}. If the technical memorandum style is used, the .CS 
macro generates the “Cover Sheet for Technical Memorandum”. The data that appear in the lower left corner 
of the technical memorandum cover sheet (counts of: pages of text, other pages, total pages, figures, tables, and 
references) are generated automatically (0 is used for “other pages”). These values may be changed by supplying 
the corresponding arguments to the .CS macro. If the released-paper style is used, all arguments to .CS are ig- 
nored. 


11. References 


There are two macros (.RS and .RF) that delimit the text of references, a string that automatically numbers 
the subsequent references, and an optional macro (.RP) that produces reference pages within the document. 


11.1 Automatic Numbering of References 


Automatically numbered references may be obtained by typing \*(Rf (invoking the string Rf) immediately 
after the text to be referenced. This places the next sequential reference number (in a smaller point size) en- 
closed in brackets one-half line above the text to be referenced. Reference count is kept in the Rf number regis- 
ter. 


‘11.2 Delimiting Reference Text 


.RS [string-name] 


The .RS and .RF macros are used to delimit text of each reference as shown below: 
A line of text to be referenced.\*(Rf 


-RS 
reference text 
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11.3 Subsequent References 
The .RS macro takes one argument, a string-name. For example: 


-RS aA 
reference text 
RF 


The string aA is assigned the current reference number. This string may be used later in the document as 
the string call, \*(aA, to reference text which must be labeled with a prior reference number. The reference 
is output enclosed in brackets one-half line above the text to be referenced. No .RS/.RF pair is needed for subse- 
quent references. 


11.4 Reference Page 
.RP [arg1] [arg2] 


A reference page, entitled by default “References”, will be generated automatically at the end of the docu- 
ment (before table of contents and cover sheet) and will be listed in the table of contents. This page contains 
the reference items (i.e., reference text enclosed within .RS/.RF pairs). Reference items will be separated by 
a space (one-half a vertical space) unless the Ls register is set to 0 to suppress this spacing. The user may change 
the reference page title by defining the Rp string: 


.ds Rp " New Title" 

The .RP (reference page) macro may be used to produce reference pages anywhere else within a document 
(i.e., after each major section). It is not needed to produce a separate reference page with default spacings at 
the end of the document. 

Two .RP macro arguments allow the user to control resetting of reference numbering and page skipping. 


arg] Meaning 


0 reset reference counter (default) 
1 do not reset reference counter 


arg2 Meaning 
0 put on separate page (default) 
1 do not cause a following .SK 
2 do not cause a preceding .SK 
3 no .SK before or after 


If no .SK is issued by the .RP macro, a single blank line will separate the references from the following/ 


preceding text. The user may wish to adjust spacing. For example, to produce references at the end of each major 
section: 

sp 3 

REE? 


-H 1" Next Section" 
12. Miscellaneous Features 
12.1 Bold, Italic, and Roman Fonts 


.B [bold-arg] [previous-font-arg] ... 
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I [italic-arg] [previous-font-arg] ... 


When called without arguments, the .B macro changes the font to bold and the .I macro changes to underlin- 
ing (italic). This condition continues until the occurrence of the .R macro which causes the Roman font to be 
restored. Thus: 


Zk 
here is some text. 
.R 


yields underlined text via the nroff and italic text via the troff(1) formatter. 

If the .B or .I macro is called with one argument, that argument is printed in the appropriate font (under- 
lined in the nroff formatter for .1). Then the previous font is restored (underlining is turned off in the nroff 
formatter). If two or more arguments (maximum six) are given with a .B or .I macro call, the second argument 
is concatenated to the first with no intervening space (1/12 space if the first font is italic) but is printed in the 
previous font. Remaining pairs of arguments are similarly alternated. For example: 

italic "text" right-justified 
produces 


Italic text right -justified 


The .B and .I macros alternate with the prevailing font at the time the macros are invoked. To alternate 
specific pairs of fonts, the following macros are available: 


IE -Bl><1Ro sR RB: 2B 
Each macro takes a maximum of six arguments and alternates arguments between specified fonts. 


When using a terminal that cannot underline, the following can be inserted at the beginning of the document 
to eliminate all underlining: 


rm ul 
rm cu 


Note: Font changes in headings are handled separately {4.2.2.4.1}. 
12.2 Justification of Right Margin 
SA [arg] 


The .SA macro is used to set right-margin justification for the main body of text. Two justification flags 
are used—current and default. The “.SA 0” call sets both flags to no justification; it acts like the .na request. 
The “.SA 1” call sets both flags to cause both right and left justification, the same as the .ad request. However, 
calling .SA without an argument causes the current flag to be copied from the default flag, thus performing 
either a .na or .ad depending on the default. Initially, both flags are set for no justification in the nroff 
formatter and for justification in the troff formatter. 


In general, the no adjust request (.na) can be used to ensure that justification is turned off, but SSA should 
be used to restore justification, rather than the .ad request. In this way, justification or no justification for the 
remainder of the text is specified by inserting “SA 0” or “.SA 1” once at the beginning of the document. 
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12.3 SCCS Release Identification 


The REstring contains the SCCS release and the MM text formatting macro package current version level. 
For example: 


This is version \*(RE of the macros. 
produces 
This is version 10.129 of the macros. 


This information is useful in analyzing suspected bugs in MM. The easiest way to have the release identifica- 
tion number appear in the output is to specify —rD1 {2.4} on the command line. This causes the RE string to 
be output as part of the page header {9.2.1}. 


12.4 Two-Column Output 


.2C 
text and formatting requests (except another .2C) 
AC 


The MM text formatting macro package can format two columns on a page. The .2C macro begins 2-column 
processing which continues until a .1C macro (1-column processing) is encountered. In 2-column processing, 
each physical page is thought of as containing 2-columnar “pages” of equal (but smaller) “page” width. Page 
headers and footers are not affected by 2-column processing. The .2C macro does not balance 2-column output. 


It is possible to have full-page width footnotes and displays when in 2-column mode, although default action 
is for footnotes and displays to be narrow in 2-column mode and wide in 1-column mode. Footnote and display 
width is controlled by the .WC (width control) macro, which takes the following arguments: 


arg Meaning 

N Default mode (-WF, —FF, —WD, FB). 

WF Wide footnotes (even in 2-column mode). 

—WF DEFAULT: Turn off WF. Footnotes follow column mode; wide in 1-column mode (1C), narrow 
in 2-column mode (2C), unless FF is set. 

FF First footnote. All footnotes have same width as first footnote encountered for that page. 

—FF DEFAULT: Turn off FF. Footnote style follows settings of WF or -WF. 

Wh .-. Wide displays (even in 2-column mode). 

—-WD DEFAULT: Displays follow the column mode in effect when display is encountered. 

FB DEFAULT: Floating displays cause a break when output on the current page. 

—FB Floating displays on current page do not cause a break. 


Note: The “.WC WD FF” command will cause all displays to be wide and all footnotes on a page to be 
the same width while “.WC N” will reinstate default actions. If conflicting settings are given to .WC, the 
last one is used. A “.WC WF —WE” command has the effect of a “.WC —WF”. 
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12.5 Column Headings for Two-Column Output 
Note: This section is intended only for users accustomed to writing formatter macros. 


In 2-column processing output, it is sometimes necessary to have headers over each column, as well as head- 
ers over the entire page. This is accomplished by redefining the .TP macro {9.6} to provide header lines both for 
the entire page and for each of the columns. For example: 


.de TP 

Sp 2 

tl Page \\nP?OVERALL” 

tl ’ TITLE” 

Sp 

nf 

.ta 16C 381R 34 500 65R 
leftOcenterOrightOleftOcenterOright 
Ofirst columnOOOsecond column 
fi 

Sp 2 


where @ stands for the tab character. 


The above example will produce two lines of page header text plus two lines of headers over each column. 
Tab stops are for a 65-en overall line length. 


12.6 Vertical Spacing 
SP [lines] 


There exists several ways of obtaining vertical spacing, all with different effects. The .sp request spaces 
the number of lines specified unless the no space (.ns) mode is on, then the .sp request is ignored. The no space 
mode is set at the end of a page header to eliminate spacing by a .sp or .bp request that happens to occur at 
the top of a page. This mode can be turned off by the .rs (restore spacing) request. 


The .SP macro is used to avoid the accumulation of vertical space by successive macro calls. Several SP 
calls in a row will not produce the sum of the arguments but only the maximum argument. For example, the 
following produces only three blank lines: 


SP 2 
SP 3 
SP 


Many MM macros utilize .SP for spacing. For example, “.LE 1” {5.1.3} immediately followed by “.P” {4.1} pro- 


-duces only a single blank line (one-half a vertical space) between the end of the list and the following paragraph. 


An omitted argument defaults to one blank line (one vertical space). Negative arguments are not permitted. 
The argument must be unscaled but fractional amounts are permitted. The SP macro (as well as .sp) is also 
inhibited by the .ns request. 
12.7 Skipping Pages 

.SK [pages] 


The .SK macro skips pages but retains the usual header and footer processing. If the pages argument is 
omitted, null, or 0, .SK skips to the top of the next page unless it is currently at the top of a page (then it does 
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nothing). The “.SK n” skips n pages. The .SK macro always positions text that follows it at the top of a page, 
while “SK 1” always leaves one page blank except for the header and footer. 


12.8 Forcing an Odd Page 


.OP 


The .OP macro is used to ensure that formatted output text following the macro begins at the top of an 
odd-numbered page. If currently at the top of an odd-numbered page, text output begins on that page (no motion 
takes place). If currently on an even page, text resumes printing at the top of the next page. If currently on an 
odd page (but not at the top of the page), one blank page is produced, and printing resumes on the next odd- 
numbered page after that. 


12.9 Setting Point Size and Vertical Spacing 
8 [point size] [vertical spacing] 


In the troff formatter, the default point size (obtained from the MM register S {2.4}) is 10 points, and the 
vertical spacing is 12 points (six lines per inch). Prevailing point size and vertical spacing may be changed by 


invoking the .S macro. 
The mnemonics D (default value), C (current value), and P (previous value) may be used for both arguments. 

e If an argument is negative, current value is decremented by the specified amount. 

e If an argument is positive, current value is incremented by the specified amount. 

e If an argument is unsigned, it is used as the new value. 

e If there are no arguments, the .S macro defaults to P. 

e If the first argument is specified but the second is not, then (default) D is used for the vertical spacing. 
Default value for vertical spacing is always two points greater than the current point size. Footnotes {8} are two 


points smaller than the body with an additional 3-point space between footnotes. A null(" " ) value for either 
argument defaults to C (current value). Thus, if nis a numeric value: 


S =5PP 
S""n =SCn 
Sn"" =S8nC 
Sn =SnD 
on =SCD 
oe = 5) 6C 
Snn =5 nn 


If the first argument is greater than 99, the default point size (10 points) is restored. If the second argument 
is greater than 99, the default vertical spacing (current point size plus two points) is used. For example: 


5 100 =.5 10 12 
814111 =5 1416 


The .SM macro allows the user to reduce by one point the size of a string: 


.SM stringl |string2] [string3] 
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If the third argument is omitted, the first argument is made smaller and is concatenated with the second 
argument if the latter is specified. If all three arguments are present (even if any are null), the second argument 
is made smaller and all three arguments are concatenated. For exam ple: 


INPUT OUTPUT 
SM X x 
SMX Y XY 
SMYXY YXY 
SM YXYX YXYX 
SM YXYX ) YXYX) 
SM (YXYX) — (YXYx) 
SM YXYX""  YxyYx 


12.10 Producing Accents 


The following strings may be used to produce accents for letters: 


INPUT OUTPUT 


Grave accent c\** ¢ 
Acute accent e\*? é 
Circumflex o\* 0 
Tilde n\* ii 
Cedilla c\t, ¢ 
Lower-case umlaut u\*: ii 
Upper-case umlaut U\4; U 


12.11 Inserting Text Interactively 
-RD [prompt] [diversion] [string] 
The .RD (read insertion) macro allows a user to stop the standard output of a document and to read text 
from the standard input until two consecutive newline characters are found. When newline characters are en- 


countered, normal output is resumed. 


e The prompt argument will be printed at the terminal. If not given, .RD signals the user with a BEL on 
terminal output. 


e The diversion argument allows the user to save all text typed in after the prompt in a macro whose name 
is that of the diversion. 


e The string argument allows the user to save for later reference the first line following the prompt in 
the named string. 


The .RD macro follows the formatting conventions in effect. Thus, the following examples assume that the 


-RD is invoked in no-fill mode (.nf): 


-RD Name aA bB 
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produces 
Name: J. Jones (user types name) 
16 Elm Rd., 
Piscataway 
The diverted macro .aA will contain 
J. Jones 
16 Elm Rd., 
Piscataway 


The string bB (\*bB) contains “J. Jones”. 


A newline character followed by an EOF (user specifiable CONTROL d) also allows the user to resume nor- 
mal output. 


13. Errors and Debugging 
13.1 Error Terminations 
When a macro detects an error, the following actions occur: 
e A break occurs. 


e The formatter output buffer (which may contain some text) is printed to avoid confusion regarding loca- 
tion of the error. 


e A short message is printed giving the name of the macro that detected the error, type of error, and ap- 
proximate line number in the current input file of the last processed input line. Krror messages are ex- 
plained in Table 4.D. 


e Processing terminates unless register D {2.4} has a positive value. In the latter case, processing continues 
even though the output is guaranteed to be deranged from that point on. 


The error message is printed by outputting the message directly to the user terminal. If an output filter, 
such as 300(1), 450(1), or hp(1) is being used to post-process the nroff formatter output, the message may 
be garbled by being intermixed with text held in that filter’s output buffer. 


Note: If any of ew(1), eqn(1)/neqn, and tbl(1) programs are being used and if the —olist option of the 
formatter causes the last page of the document not to be printed, a harmless “broken pipe” message may 
result. 


13.2 Disappearance of Output 


Disappearance of output usually occurs because of an unclosed diversion (e.g., a missing .DE or .FE macro). 
Fortunately, macros that use diversions are careful about it, and these macros check to make sure that illegal 
nestings do not occur. If any error message is issued concerning a missing .DE or .FE, the appropriate action 
is to search backwards from the termination point looking for the corresponding associated .DF, .DS, or .F'S 
(since these macros are used in pairs). 


The following command: 


grep —n’*\.[ECFRT][EFNQS)’ files ... 


Page 214 


LS nae CD em Be te FF 


6/82 ISSUE 1 DOCUMENT PROCESSING GUIDE 


prints all the .DF, .DS, .DE, .EQ, .EN, .FS, .FE, .RS, .RF, .TS, and .TE macros found in files ... , each preceded 
by its file name and the line number in that file. This listing can be used to check for illegal nesting and/or omis- 
sion of these macros. 


14. Extending and Modifying MM Macros 
14.1 Naming Conventions 
In this part, the following conventions are used to describe names: 
Digit 
Lowercase letter 
Uppercase letter 


Any alphanumeric character (: a, n, A, or 1, ie., letter or digit) 
any nonalphanumeric character (special character) 


AAS S 


All other characters are literals (i.e., characters stand for themselves). 


Request, macro, and string names are kept by the formatters in a single internal table; therefore, there must 
be no duplication among such names. Number register names are kept in a separate table. 


14.1.1 Names Used by Formatters 
requests: aa (most common) 
an (only one, currently: c2) 
registers: aa (normal) 
.x (normal) 
.s (only one, currently: .$) 
a. (only one, currently: c.) 
% (page number) 
14.1.2 Names Used by MM 
macros and strings: A, AA, Aa (accessible to users; e.g., macros P and IIU, strings F, BU, and Lt) 
nA (accessible to users; only two, currently: 1C and 2C) 
aA (accessible to users; only one, currently: nP) 
s (accessible to users; only the seven accents, currently {12.10}) 
)x, }x, ]x, >x, ?x (internal) 
registers: An, Aa (accessible to users; e.g., H1, Fg) 
A (accessible to users; meant to be set on the command line; e.g., C) 


:X, 3X, #x, ?x, x (internal) 
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14.1.3 Names Used by CW, EQN/NEQN, and TBL Programs 


The ew(1) program is the constant-width font preprocessor for the troff formatter. It uses the following 
five macro names: 


.CD, .CN, .CP, .CW, and .PC. 


This preprocessor also uses the number register names cE and cW. Mathematical equation 
preprocessors, eqn(1) and neqn, use registers and string names of the form nn. The table 
preprocessor, tbl(1), uses T&, T/, and TW, and names of the form: 


aa = ak Soins one (ge pal aS 
14.1.4 Names Defined by User 


Names that consist either of a single lowercase letter or a lowercase letter followed by a character other 
than a lowercase letter (names .c2 and .nP are already used) should be used to avoid duplication with already 
used names. The following is a possible naming convention: 


macros: aA (eg., bG, kW) 
strings: as (e.g., c), f], p}) 
registers: a (e.g., f, t) 


14.2 Sample Extensions 
14.2.1 Appendix Headings 
The following is a way of generating and numbering appendix headings: 


-nr Hu 1 

nra0 

.de aH 

Bho) er oa | 

ire 0 

.PH "”’ Appendix \\na-\\\\\\\\nP’" 
SK 

AU NNSE 


After the above initialization and definition, each call of the form .aH " title" begins a new page (with the 
page header changed to “Appendix a-n”) and generates an unnumbered heading of title, which, if desired, can 
be saved for the table of contents. Those who wish apppendix titles to be centered must, in addition, set the regis- 
ter He to 1 {4.2.2.3}. 


14.2.2 Hanging Indent With Tabs 


The following example illustrates the use of the hanging indent feature of variable-item lists {5.1.1.6}. A 
user-defined macro is defined to accept four arguments that make up the mark. In the output, each argument 
is to be separated from the previous one by a tab; tab settings are defined later. Since the first argument may 
begin with a period or apostrophe, the “\&” is used so that the formatter will not interpret such a line as a 
formatter request or macro call. 


Note: The 2-character sequence “\&” is understood by formatters to be a “zero-width” space. It causes 
no output characters to appear, but it removes the special meaning of a leading period or apostrophe. 
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The “\t” is translated by the formatter into a tab. The “\c” is used to concatenate the input text that follows 
the macro call to the line built by the macro. The macro and an example of its use are: 


.de aX 
LI 


\&\\$1\E\\ $2\t\\$3\t\\$4\t\c 


ta 8 14 20 24 
.VL 36 
.aX .nh off \— no 
No hyphenation. 
Automatic hyphenation is turned off. 
& Words containing hyphens 
(e.g., mother-in-law) may still be split across lines. 
.aX .hy on \— no 
Hyphenate. 
Automatic hyphenation is turned on. 
.aX .he\<sp>c¢ none none no 
Hyphenation indicator character is set to “e” or 
removed. . 
During text processing, the indicator is suppressed 
and will not appear in the output. 
Prepending the indicator to a word has the effect 
of preventing hyphenation of that word. 


€ ns 


where <sp> stands for a space. 
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) 

| 

| 

| The resulting output is: 

} 


nh off — no No hyphenation. Automatic hyphenation is turned off. Words con- 
| taining hyphens (e.g., mother-in-law) may still be split across lines. 


-hy on == no Hyphenate. Automatic hyphenation is turned on. 


text processing, the indicator is suppressed and will not appear in 
the output. Prepending the indicator to a word has the effect of 


; & -hee none none no Hyphenation indicator character is set to “c” or removed. During 
preventing hyphenation of that word. 

J 

3 

; 
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15. Summary 


The following are qualities of MM that have been emphasized in its design in approximate order of impor- 
tance: 


e Robustness in the face of error—A user need not be an nroff/troff expert to use MM macros. When 
the input is incorrect, either the macros attempt to make a reasonable interpretation of the error or 
an error message describing the error is produced. An effort has been made to minimize the possibility 
that a user would get cryptic system messages or strange output as a result of simple errors. 


e Kase of use for simple documents—It is not necessary to write complex sequences of commands to pro- 
duce documents. Reasonable macro argument default values are provided where possible. 


e Parameterization—There are many different preferences in the area of document styling. Many param- 
eters are provided so that users can adapt input text files to produce output documents to their respec- 
tive needs over a wide range of styles. 


e Extension by moderately expert users—A strong effort has been made to use mnemonic naming conven- 
tions and consistent techniques in construction of macros. Naming conventions are given so that a user 
can add new macros or redefine existing ones if necessary. 


DOCUMENT PROCESSING GUIDE ISSUE 1 6/82 
: 
| 
e Device independence—A common use of MM is to produce documents on hard copy via teletypewriter | 
terminals using the nroff formatter. Macros can be used conveniently with both 10- and 12-pitch termi- | 
nals. In addition, output can be displayed on an appropriate CRT terminal. Macros have been con- 
structed to allow compatibility with the troff(1) formatter so that output can be produced on both a 
. 


phototypesetter and a teletypewriter/CRT terminal. 


e Minimization of input—The design of macros attempts to minimize repetitive typing. For example, if 
a user wants to have a blank line after all first- or second-level headings, the user need only set a specific 
parameter once at the beginning of a document rather than type a blank line after each such heading. 


e Decoupling of input format from output style—There is but one way to prepare the input text although 
the user may obtain a number of output styles by setting a few global flags. For example, the .H macro | 
is used for all numbered headings, yet the actual output style of these headings may be made to vary i 
from document to document or within a single document. | 
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INPUT: 


«ND "May 31, 1979" 

eTL 334455 

Out-of-Hours Course Description 

eAU "D, We. Stevenson" DWS PY 9876 5432 1X-123 

MT 0 

=DS 

J. M. Jones: 

DE 

rg 

Please use the following description for the out-of-hours course 
ol 

Document Preparation on the UNIX# 

oR 

A oS eid 

Trademark of Bell Laboratories. 

FE 

-I "Time-Sharing Operating System:" 

a 

The course is intended for clerks, typists, and others 
who intend to use the UNIX system for preparing documentation, 
The course will cover such topics as: 

VL 18 

«LI Environment: 

utilizing a time-sharing computer system; 

accessing the system; using appropriate output terminals. 
LI Files: 

how text is stored on the system; 

directories; manipulating files. 

«LI “Text editing: 

how to enter text so that subsequent revisions are easier to make; 
how to use the editing system to add, delete, and move lines of text; 
how to make corrections, 

eLI "Text processing:" 

basic concepts; 

use of general purpose formatting packages. 

-LI "Other facilities:" 

additional capabilities useful to the typist such as the 
elo" spell. arrr* 

and 

el grep 

commands, and a desk-calculator package. 

Fue > 

2oG jrm 

NS 0 

S. P. 'ename 

H. 0. Del 

M. Hill 

NE 


Fig. 4.1 — Examples of a Simple Letter (Sheet 1 of 3) 
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nreff OUTPUT: 


Bell Laberateries 


subject: Out-of-Hours Course Description - date: May 31, 1979 
Case 334455 


from: D, W. Stevenson 
PY 9876 
1X-123 x5432 


J. M. Jones; 


Please use the following description for the out-of-hours course 


= ee a ae 


The course is intended for clerks, typists, and ethers who intend to use 
the UNIX system for preparing documentation. The course will cover such 
topics as: 


Environment: utilizing a time-sharing computer system; accessing 
the system; using appropriate output terminals. 


Files: how text is stored on the system; directories; 
manipulating files. 


Text editing: how to enter text so that subsequent revisions are 
easier to make; how to use the editing system to add, 
delete, amd move lines of text; how to make 
corrections, 


Text processing: basic concepts; use of general-purpose formatting 
packages, 


Other facilities: additional capabilities useful to the typist such as 
the spell, diff, and grep commands, and a desk- 
calculator package. 


PY-9876-DWS- jrm D. W. Stevenson 


Copy to 

S. P. Lename 
H. O, Del 

M,. Hill 


# Trademark of Bell Laboratories. 


Fig. 4.1 — Examples of a Simple Letter (Sheet 2 of 3) 
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Bell Laboratories 


subject: Out-of-Hours Course Description - Case 334455 date: May 31, 1979 


from: D. W. Stevenson 
PY 9876 
1X-123 x5432 


J. M. Jones: 


Please use the following description for the Out-of-Hours course Document Preparation on the 
UNIX* Time-Sharing System: 


The course is intended for clerks, typists, and others who intend to use the UNIX system for 
preparing documentation. The course will cover such topics as: 


Environment: utilizing a time-sharing computer system; accessing the system; using 
appropriate output terminals, 

Files: how text is stored on the system; directories; manipulating files. 

Text editing: how to enter text so that subsequent revisions are easier to make; how to 


use the editing system to add, delete, and move lines of text; how to make 
corrections. 


Text processing: _ basic concepts; use of general-purpose formatting packages. 


Other facilities: additional capabilities useful to the typist such as the spell, diff, and grep 
commands, and a desk-calculator package. 


PY-9876-DWS-jrm D. W. Stevenson 
Copy to 
S. P. Lename 


H. O. Del 
M. Hill 


* Trademark of Bell Laboratories. 


Fig. 4.1 — Examples of a Simple Letter (Sheet 3 of 3) 
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INPUT: 


ie 

«FD 10 

This example illustrates several footnote styles 

for both labeled and automatically numbered footnotes. 
With the footnote style set to the NROFF default, 

process the first footnote\*F 

«FS 

This is the first footnote text example (.FD 10). 

This is the default style for NROFF, 

The right margin is not justified. 

Hyphenation is not permitted, 

Text is indented, and the automatically generated label is 
right justified in the text-indent space. 

FE 

and follow it by a second footnote, ####* 

.FS eae 

This is the second footnote text example (.FD 10). 

This is also the default NROFF style but with a long 
footnote label (*****) provided by the user. 

aE 

Soe 

Footnote style is changed by using the .FD macro to 
specify hyphenation, right margin justification, 
indentation, and left justification of the label. 

This produces the third footnote,\*F 

af 

This is the third footnote example (.FD 1). 

The right margin is justified, the footnote text is indented, 
and the label is left justified in the text-indent space. 
Although not necessarily illustrated by this example, 
hyphenation is permitted, 

FE 

and then the fourth footnote.\(dg 

FS + 

This is the fourth footnote example (.FD 1). 

The style is the same as the third footnote. 

eFE 

«FD 6 

Footnote style is set again via the .FD macro for no hyphenation, 
no right margin justification, 

no indentation, and with the label left justified, 

This produces the fifth footnote.\*#F 

fg oN 

This is the fifth footnote example (.FD 6). 

The right margin is not justified, hyphenation is not permitted, 
footnote text is not indented, 

and the label is placed at the beginning of the first line. 
S32 


Fig. 4.2 — Examples of Footnotes (Sheet 1 of 2) 
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27 ie 


OUTPUT: 


This example illustrates several footnote styles for both 
labeled and automatically numbered footnotes. With the 
footnote style set to the NROFF default, process the first 
footnote and follow it by a second footnote, *###* Footnote 
style is changed by using the .FD macro to specify 
hyphenation, right margin justification, indentation, and 
left Just] fication of the label. This produces the third 
footnote, and then the fourth footnote.+ Footnote style is 
e set again via the .FD macro for no hyphenation, no right 

margin justification, no indentation, and with the_ label 
left justified. This produces the fifth footnote, 


1. This is the first footnote text example (.FD 10). This 
is the default style for NROFF, The right margin is not 
justified. Hyphenation is not permitted. Text is 
indented, and the automatically generated label is right 
justified in the text-indent space, 


e##*#* This is the second footnote text example (.FD 10). 
This is also the default NROFF style but with a long 
footnote label (#####) provided by the user. 


2. This is the third footnote example (.FD 1). The right 
& margin is justified, the footnote text is indented, and 
the label is left justified in the text-indent space. 
Although not necessarily illustrated by this example, 
hyphenation is permitted, 


4- 


This is the fourth footnote example (.FD 1). The style 
is the same as the third footnote. 


& 3. This is the fifth footnote example (.FD 6). The right 
margin is not justified, hyphenation is not permitted, 
footnote text is not indented, and the label is placed at 
the beginning of the first line. 


Fig. 4.2 — Examples of Footnotes (Sheet 2 of 2) 
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TABLE 4.A 


MM MACRO NAMES SUMMARY 


DESCRIPTION {PARAGRAPH} 


1-column processing {12.4} 
YS 


2-column processing {12.4} 
2C 


Abstract end {6.5} 
AK 


Alternate format of “Subject/Date/From” block {6.9} 
.AF [company-name] 


Automatically incremented list start {5.1.1.1} 
.AL [type] [text-indent] [1] 


Abstract start {6.5} 
.AS [arg] [indent] 


Author’s title {6.3} 

AT [title] ... 

| Author information {6.3} 

AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] [arg] 


Approval signature {6.11.3} 
.AV [name] 


Bold {12.1} 
.B [bold-arg] [previous-font-arg]| [bold] [prev] [bold] [prev] 


Bottom block end {9.7} 
.BE 


Bold/Italic {12.1} 
.BI [bold-arg] [italic-arg] [bold] [italic] [bold] |italic] 


Bullet list start {5.1.1.2} 
.BL [test-indent] [1] 


Bold/Roman {12.1} 
BR [bold-arg] [Roman-arg] [bold] [Roman] [bold] [Roman 


Bottom block start {9.7} 

.BS 

Cover sheet {10.2} 

.CS [pages] [other] [total] [figs] [tbls] [refs] 
Display end {7.1} 

.DE 

Display floating start {7.2} 

_DF [format] [fill] [right-indent] 


Dash list start {5.1.1.3} 
.DL |[text-indent] [1] 
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TABLE 4.A (Contd) 
MM MACRO NAMES SUMMARY 
DESCRIPTION PARAGRAPH 

Display static start {7.1} 
.DS [format] [fill] [right-indent] 
Equation caption {7.5} 
EC [title] [override] [flag] 
Even-page footer {9.2.5} 
EF [arg] 


Even-page header {9.2.2} 
EH [arg] 


End equation display {7.4} 
.EN 

Equation display start {7.4} 
EQ [label] 

Exhibit caption {7.5} 

.EX [title] [override] [flag] 
Formal closing {6.11} 

FC [elosing] 

Footnote default format {8.3} 
FD [arg] [1] 

Footnote end {8.2} 

FE 


Figure title {7.5} 
FG [title] [override] [flag] 


Footnote start {8.2} 

FS [label] 

Heading—numbered {4.2} 

H level [heading-text] [heading-suffix] 


Hyphenation character {3.4} 
.HC [hyphenation-indicator] 


Heading mark style {42.2.5} 


(Arabic or Roman numerals, or letters) 
.HM [arg1] ... [arg7] 


Heading—unnumbered {4.3} 
.HU heading-text 


Heading user exit X (before printing heading) {4.6} 
.HX dlevel rlevel heading-text 


*See note at end of table. 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


DESCRIPTION PARAGRAPH 


Heading user exit Y (before printing heading) {4.6} 
-HY dlevel rlevel heading-text 


Heading user exit Z (after printing heading) {4.6} 
HZ dlevel rlevel heading-text 


Italic (underline in the nroff formatter) {12.1} 
I [italic-arg] [previous-font-arg] [italic] [prev] [italic] [prev] 


Italic/Bold {12.1} 
IB [italic-arg] [bold-arg] [italic] [bold] [italic] [bold] 


Italic/Roman fio1} 
IR [italic-arg] [Roman-arg] [italic] [Roman] [italic] [Roman] 


List begin {5.2} 

LB text-indent mark-indent pad type [mark] |LI-space] [LB- 
space] 

List-status clear {5.3} 

LLC [list-level] 


List end {5.1.3} 
-LE [1] 

List item {5.1.2} 
.LI [mark] [1] 


Marked list start {5.1.1.4} 
.ML mark |text-indent] [1] 


Memorandum type {6.7} 
.MT [type] [addressee] or .MT [4] [1] 


New date {6.8} 
.ND new-date 


Notation end {6.11.2} 
NE 


Notation start {6.11.2} 
.NS [arg] 


Double-line indented paragraphs {4.1} 
ar 

Odd-page footer {9.2.6} 

.OF [arg] 

Odd-page header {9.2.3} 

OTT [arg] 


Other keywords for the Technical Memorandum cover sheet {6.6} 
OK [keyword] ... 


*See note at end of table. 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


MACRO DESCRIPTION PARAGRAPH 


Odd page {12.8} 
OP 


Paragraph {4.1} 

-P [type] 

Page footer {9.2.4} 
.PF [arg] 

Page header {9.2.1! 
.PH [arg] 


Proprietary marking {9.9} 
-PM [eode] 


Page-header user exit {9.6} 
PX 


Return to regular (Roman) font {12.1} 
R 


Roman/bold {12.1} 
-RB [Roman-arg] [bold-arg] [Roman] [bold] [Roman] [bold] 


Read insertion from terminal {12.11} 
.RD [prompt] [diversion] [string] 
Reference end {11.2} 

RF 


Roman/Italic {12.1} 
-RI [Roman-arg] [italic-arg] [Roman] [italic] [Roman] [italic] 


Reference list start {5.1.1.5} 
.RL [text-indent] [1] 


Produce reference page {11.4} 
-RP [arg] [arg] 

Reference start {11.2} 

-RS [string-name] 


Set troff formatter point size and vertical spacing {12.9} 
.5 [size] [spacing] 


Set adjustment (right-margin justification) default {12.2} 
2A [arg] 


Signature line {6.11.1} 
SG [arg] [1] 


Skip pages {12.7} 
SK [pages] 


*See note at end of table. 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


MACRO DESCRIPTION PARAGRAPH 


Make a string smaller {12.9} 
‘SM string] [string2] [string3] 
Space vertically {12.6} 

SP [lines] 

Table title {7.5} 

TB [title] [override] [flag] 


Table of contents {10.1} 
.TC [slevel] [spacing] [tlevel] [tab] [head1] [head2] [head3] 
{head4] [head5] 


Table end {7.3} 
.TE 


Table header {7.3} 
.TH [N] 


Title of memorandum {6.2} 
.TL [charging-case] [filing-case] 


Technical Memorandum number(s) {6.4} 
_TM [number] ... 


Top-of-page macro {9.6} 
“cP 


Table start {7.3} 

TS [H] 

Table of contents user exit {10.1} 
.TX 


Table of contents user exit {10.1} 
(suppresses “CONTENTS”) 
Ly 


Variable-item list start {5.1.1.6} 
.VL text-indent [mark-indent] [1] 


; 
: A Vertical margins {9.8} 
) .VM [top] [bottom] 


Footnote and Display Width control {12.4} 
-WC [format] 


*Macros marked with an asterisk are not, in general, called (invoked) 
directly by the user. They are “user exits” defined by the user and called 
by the MM macros from inside header, footer, or other macros. 
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TABLE 4.B 
STRING NAMES SUMMARY 


STRING 
NAME DESCRIPTION {PARAGRAPH} 


Bullet {3.7} 

NROFE: @ 

TROFF: e 

Table of contents indent list {10.1} 

Up to seven args (must be scaled) for heading levels 


Date {6.8} 
Current date, unless overridded 
Month, day, year (e.g., July 16, 1982) 


Em dash string {3.8} 
Produces an em dash in the troff formatter and a double hyphen 
in nroff 


Footnote numberer {g.14 
NROFF:\u \\n+(-p\d 
TROFF:\y‘~.4m’\s-3 \\n+(:p\s0\v‘°.4m’ 


Heading font list {4.2.2.4.1} 


Up to seven codes for heading levels 1 through 7 
3 3 2 2 2 2 2(levels1 and 2 bold, 3 through 7 underlined in the 
nroff formatter and italic in troff) 


Heading point size list {4.2.2.4.3} 
Up to seven codes for heading levels 1 through 7 


Title for LIST OF EQUATIONS {7.6} 
Title for LIST OF FIGURES {7.6} 
Title for LIST OF TABLES {7.6} 
Title for LIST OF EXHIBITS {7.6} 


SCCS Release and Level of MM {12.3} 
Release.Level (e.g., 10.129) 


Reference numberer {11.1} 


Title for references {11.4} 


Trademark string {3.9} : 
Places the letters “I'M” one-half line above the text that it follows 


Seven accent strings are also available {12.10}. 


Note 1: If the released-paper style is used, then, in addition to the above 
strings, certain BTL location codes are defined as strings; these loca- 
tion strings are needed only until the .MT macro is called {6.7} . 
Currently, the following are recognized: 


AK, AL, ALF, CB, CH, CP, DR, FJ, HL, HO, HOH, HP, IH, IN, 
INI, TW, MH, MV, PY, RD, RR, WB, WH, and WV. 


Note 2: Paragraph 1.5 has notes on setting and referencing strings. 
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TABLE 4.C 


NUMBER REGISTER NAMES SUMMARY 


DESCRIPTION {PARAGRAPH} 


Handles preprinted forms and Bell System logo {2.4} 
0, [0:2] 


Inhibits printing author’s location, department, room, and 
extension in “from” portion of a memorandum {6.3} 

1, [0:1] 

Copy type {2.4} 

Original, Draft, ete. 

0 (Original), [0:4] 

Contents level {4.4} 


Level of headings saved for table of contents 
2, [0:7] 


Placement of list of figures, etc. {10.1} 
1 (on separate pages), [0:1] 


Debug flag {2.4} 
0, [0:1] 


Display eject register for floating displays {7.2} 

0, [0:1] 

Display format register for floating displays {7.2} 
5, 10:5] 

Static display pre- and post-space {7.1} 

1, [0:1] 

Controls font of the Subject/Date/From fields {2.4} 
1 (nroff) 0 (troff), [0:1] 


Equation counter, used by .EC macro {7.5} 
0, [0:?], incremented by one for each .EC call. 


Page-ejection flag for headings {4.2.2.1} 
0 (no eject), [0:7] 


Equation label placement {7.4} 
0 (right-adjusted), [0:1] 


Exhibit counter, used by .EX macro {7.5} 
0, [0:7], incremented by one for each .EX call. 


Figure counter, used by .FG macro {7.5} 
(0, [0:?], ineremented by one for each .FG call. 


Footnote space (i.e., spacing between footnotes) {8.4} 
1, [0:7] 


H1 Heading counters for levels 1 through 7 {4.2.2.5} 

through 0, [0:?], incremented by .H of corresponding level or .TU if at 

EY level given by register Hu. H2 through H7 are reset to 0 by any 
heading at a lower-numbered level. 


*+See notes at end of table. 
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TABLE 4.C (Contd) 


NUMBER REGISTER NAMES SUMMARY 
DESCRIPTION {PARAGRAPH} 


Heading break level (after H and .HU) {4.2.2.2}2, [0:7] 
Ileading centering level for H and .HU {4.2.2.3} 
0 (no centered headings), [0:7] 


Heading temporary indent (after .H and .HU) {4.2.2.2} 
1 (indent as paragraph), [0:2] 


Heading space level (after II and HU) {4.2.2.2.} 
2 (space only after .H 1 and .H 2), [0:7] 


Heading type {4.2.2.5} 
For .H: single or concatenated numbers 
0 (concatenated numbers: 1.1.1, etc.), [0:1] 


Tleading level for unnumbered heading (.HU) {4.3} 
2 (.HU at the same level as .H 2, [0:7] 


Hyphenation control for body of document {3.4} 
() (automatic hyphenation off), [0:1] 


Length of page {2.4} 

66, [20:?] (11i, [2i:?] in treff formatter) 

For nroff formatter, these values are unscaled numbers 
representing lines or character positons; for troff formatter, 
these values must be scaled.. 


List of equations {7.6} 

0 (list not produced) [0:1] 

List of figures {7.6} 

1 (list produced) [0:1] 

List indent {5.1.1.1} 

6 (nroff) 5 (troff), [0:7] 

List spacing between items by level {5.1.1.1} 
6 (spacing between all levels) [0:6] 
List of tables {7.6} 

1 (list produced) [0:1] 

List of exhibits {7.6} 

1 (list produced) [0:1] 

Numbering style {2.4} 

0, [0:5] 


Numbering style for paragraphs {4.1} 
0 (unnumbered) [0:1] 


*tSee notes at end of table. 


Page 231 


DOCUMENT PROCESSING GUIDE ISSUE 1 


Page 232 


TABLE 4.C (Contd) 
NUMBER REGISTER NAMES SUMMARY 
DESCRIPTION {PARAGRAPH} 


Offset of page {2.4} 
.75i, [0:2] (0.51, [0i:?] in troff formatter) 


For nroff formatter, these values are unsealed numbers 
representing lines or character positions; for troff formatter, 


these values must be scaled. 


Table of contents page numbering style {10.1} 
0 (lowercase Roman), [0:1] 

Figure caption style {7.5} 

() (period separator), [0:1] 

Page number manager by MM {2.4} 

0, [0:?] 

Paragraph indent {4.1} 

5 (nroff) 3 (troff), [0:2] 

Paragraph spacing {4.1} 

1 (one blank space between paragraphs), [0:7] 
Paragraph type {4.1} 

0 (paragraphs always left justified), [0:2] 
“PRIVATE” header {9.10} 

0 (not printed), [0:2] 


Reference counter, used by .RS macro {11.1} 
0), [0:2], incremented by one for each .RS call. 


The troff formatter default point size {2.4} 
10, [6:36] 


Standard indent for displays {7.1} 
5 (nroff) 3 (troff), [0:7] 


Type of nroff output device {2.4} 
0, [0:2] 


Table counter, used by .TB macro {7.5} 
(), [0:2], incremented by one for each .TB call. 


Underlining style (nroff) for .H and .HU {2.4} 
0 (continuous underline when possible), [0:1] 


Width of page (line and title length) {2.4} 


6i, [10:1365] (6i, [2i:7.54i] in the troff formatter) 


*An asterisk attached to a register name indicates that this register can be set 
only from the comman line or before the MM macro definitions are read by the 
formatter {2.4, 2.5} . 


+Paragraph 1.5 has notes on setting and referencing registers. Any register 
having a single-character name can be set from the command line. 


6/82 


ee ee ee ey ee ey a a ae ee ee SE eee 


6/82 ISSUE 1 DOCUMENT PROCESSING GUIDE 


TABLE 4.D 


ERROR MESSAGES 


ERROR MESSAGE DESCRIPTION 


ys -  . kn ea 


———— OO ee eee ae 


MM Error Messages 


An MM error message has a standard part followed by a variable part. The standard part has the form: 


ERROR:(filename)input line m 


Variable parts consist of a descriptive message usually beginning with a macro name. They are listed 
below in alphabetical order by macro name, each with a more complete explanation. 


Check TL, AU, AS, AE, MT 
sequence 


Check TL, AU, AS, AE, NS, NE, 


MT sequence 


CS:cover sheet too long 


DE:no DS or DF active 


DF:illegal inside TL or AS 
DF:missing DE 


DF:missing FE 
DF:too many displays 


DS:illegal inside TL or AS 
DS:missing DE 


DS:missing FE 
FE:no FS active 
FS:missing DE 
FS:missing FI 
H:bad arg: value 


H:missing arg 


II:missing DE 


The correct order of macros at the start of a memorandum is 
shown in {6.1} . Something has disturbed this order. 


The correct order of macros at the start of a memorandum is 
shown in {6.1} , something has disturbed this order. Occurs if the 
AS 2. {6.5}macro was used. 


Text of the cover sheet is too long to fit on one page. The abstract 
should be reduced or the indent of the abstract should be decreased 
{6.5}. 


A .DE macro has been encountered, but there has not been a previ- 
ous .DS or .DF macro to match it. 


Displays are not allowed in the title or abstract. 


A .DF macro occurs within a display, i.e., a.DE macro has been 
omitted or mistyped. 


A display starts inside a footnote. The likely cause is the omission 
(or misspelling) of a .FE macro to end a previous footnote. 


More than 26 floating displays are active at once, i.e., have been 
accumulated but not yet output. 


Displays are not allowed in the title or abstract. 


A .DS macro occurs within a display, i.e., a.DE has been omitted or 
mistyped. 


A display starts inside a footnote. The likely cause is the omission 
(or misspelling) of a .FE to end a previous footnote. 


A .FE macro has been encountered with no previous .F'S to match 
it. 


A footnote starts inside a display, i.e.,a .DS or .DF occurs without 
a matching .DE. 


A previous .FS macro was not matched by a closing .FE, i.e., an 
attempt is being made to begin a footnote inside another one. 


The first argument to the .H macro must be a single digit from one 
to seven, but value has been supplied instead. , 


The .IT macro needs at least one argument. 


A heading macro (.H or .HU) occurs inside a display. 
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Ii:missing FE 


IIU:missing arg 


LB:missing arg(s) 


LB:too many nested lists 


LE:mismatched 


LI:no lists active 


ML:missing arg 


ND:missing arg 


RF:no RS active 


RP:missing RF 
RS:missing RF 


S:bad arg:value 


SA:bad arg:value 


SG:missing DE 


SG:missing FE 


SG:no authors 


VL:missing arg 


WC:unknown option 


Formatter Error Messages 


support group. 


Cannot do ev 
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ERROR MESSAGES 


ERROR MESSAGE DESCRIPTION 


A heading macro (.H or .ITU) occurs inside a footnote. 

The .1U macro needs one argument. 

The .LB macro requires at least four arguments. 

Another list was started when there were already six active lists. 


The .LE macro has occurred without a previous .LB or other list- 
initialization macro {5.1.1} . Although this is not a fatal error, 
the message is issued because there almost certainly exists some 
problem in the preceding text. 


The .LI macro occurred without a preceding list-initialization 
macro. The latter has probably been omitted or has been separated 
from the .LI by an intervening .H or .HU. 


The .ML macro requires at least one argument. 
The .ND macro requires one argument. 


The .RF macro has been encountered with no previous .RS to 
match it. 


A previous .RS macro was not matched by a closing .RF. 
A previous .RS macro was not matched by a closing .RF. 


es sag argument value has been given for the .S macro 
ipo) fag 


The argument to the SA macro (if any) must be either 0 or 1. the 
incorrect argument is shown as value. 


The 
The 
The 
The 


SG macro occurred inside a display. 

SG macro occurred inside a footnote. 

‘SG macro occurred without any previous .AU macro(s). 
.VL macro requires at least one argument. 


engiventothe.WC macro {12.4} . 


Most messages issued by the formatter are self-explanatory. Those error messages over which the user 
has some control are listed below. Any other error messages should be reported to the local system 


Caused by: 


a. setting a page width that is negative or extremely short 

b. setting a page length that is negative or extremely short 

c. reprocessing a macro package (e.g., performing a .so request on 
a macro package that was already requested on the command 
line) 

d. requesting the troff formatter (an option on a document that is 

longer than ten pages). 
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Cannot execute filename 


Cannot open filename 


Exception word list full 


Line overflow 


Nonexistent font type 


Nonexistent macro file 


Nonexistent terminal type 


Out of temp file space 


Too many page numbers 


Too many number registers 


Too many string/macro names 


Word overflow 
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ERROR MESSAGES 


ERROR MESSAGE DESCRIPTION 


Given by the .! request if the filename is not found. 


Indicates one of the files in the list of files to be processed cannot 
be opened. 


Indicates too many words have been specified in the hyphenation 
exception list (via .hw requests). 


Indicates output line being generated was too long for the format- 
ter line buffer capacity. The excess was discarded. Likely causes 
for this message are very long lines or words generated through 
the misuse of \c of the .cu request or very long equations produced 
by eqn(1)/negn. 


Indicates a request has been made to mount an unknown font. 
Indicates the requested macro package does not exist. 
Indicates the terminal options refer to an unknown terminal type. 


Indicates additional temporary space for macro definitions, diver- 
sions, etc. cannot be allocated. This message often occurs because 
of unclosed diversions (missing .FE or .DE), unclosed macro defini- 
tions (e.g., missing “..”), or a huge table of contents. 


Indicates the list of pages specified to the -o formatter option 
is too long. 


Indicates the pool of number register names is full. Unneeded reg- 
isters can be deleted by using the .rr request. 


Indicates the pool of string and macro names is full. Unneeded 
strings and macros can be deleted using the .rm request. 


Indicates a word being generated exceeds the formatter word 
buffer capacity. Excess characters were discarded. Likely causes 
for this message are very long lines, words generated through the 
misuse of \c of the .cu request, or very long equations produced by 
eqn(1)/neqn. 
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